Upon completion of this chapter, readers will be able to:
- Define information structure.
- Explain the contents and organization of different types of information structures.
Use a logical, natural structure—content and organization
The main parts of a technical-writing course focus on applications—ways technical writing skills are applied in the real world. However, these applications use varying combinations of information infrastructures. An information structure is (1) a type of information content (such as descriptive writing), (2) a way of organizing information (such as a comparison or classification), or (3) both.
The information infrastructures reviewed in this appendix are the ones commonly used in technical writing. Of course, there are other infrastructures—maybe some that scholars of technical writing have not yet pinned a label on, but these are the most common and the most readily visible. And of course some of these infrastructures blend together. The main thing is that by knowing these, you have the intellectual tools for quickly organizing and structuring just about any writing project.
What does it look like?
The biggest hurdle you may face in writing a description is remembering what the term means as it is used in this context. We all use the word loosely to refer to practically any discussion or explanation. But in this context, it means the detailed discussion of the physical aspects of a thing. That means discussing things like color, shape, size, weight, height, width, thickness, texture, density, contents, materials of construction, and so on.
For example, this sentence is not really description in our sense of the word:
A computer diskette is a device used for storing electronic data.
It explains the function or purpose but provides little or no physical detail. However, this sentence is very definitely description:
The common computer diskette is 3.5 inches by 3.5 inches and approximately 1/8 inch thick.
Contexts for Description
As mentioned earlier, descriptions are common elements in technical writing—just not quite in the same way that instructions are. Descriptions appear more often as a sentence or two here, a paragraph there, or a whole section elsewhere. Certain kinds of technical writing feature description:
- Accident reports requiring plenty of description.
- Product specifications—documents that describe design and feature of a new or changed product—have plenty of description.
- Instructions often require description to enable readers to visualize what they are doing and what they are working with.
Contents and Organization of Descriptions
The following is a review of the sections you'll commonly find in descriptions. As you read, check out the example descriptions.
Introduction. Plan the introduction to your description carefully. Make sure it does all of the following things (but not necessarily in this order) that apply to your particular description:
- Indicate the specific object about to be described.
- Indicate what the audience needs in terms of knowledge and background to understand the description.
- Provide a general description of the object.
- Include an overview of the contents of the description.
If the thing you are describing is not likely to be familiar to most of your readers, consider adding some background before you plunge into the actual description. If you are about to describe an SGO/3 density gauge to nonspecialists, you'd better first discuss what in the world the thing is, what it does, and on what part of the planet it is used.
Discussion of the parts or characteristics
The main part of your description is the discussion of each part or characteristic. You must divide the thing you are describing into parts, or characteristics, or both. Parts are easy: for example, a wooden pencil has lead, a wooden barrel, an eraser, and a metal clip. Characteristics are describable aspects of a thing but are not parts: for example, the pencil has a certain weight, length, width, and so on. If you were a budding real-estate tycoon and had to describe a vacant lot for company files, you'd probably describe it by its characteristics: its location, square footage, terrain, vegetation, access to utilities, and so on. (Check out the description of the primitive stone scraper in the examples; part of it is arranged by characteristics, and part by parts!)
Once you've divided the thing you are describing into parts, characteristics, or both, your next job is to describe each one. For mechanical things, it works well to start by defining the part, by explaining its function. After that, you describe the part from general to specific, using any of the sources of description that are appropriate.
Notice that in description, you can mix other kinds of writing. You'll find yourself explaining functions, defining terms, discussing a bit of process as you describe. That's not a problem as long as the primary focus and the majority of the content is truly description.
Discussion of the related operation or process.
At some point in a description, often at the end, it is useful to summarize the operation or process associated with the object you're describing. For example, if you've just described a mechanical pencil, you could briefly explain how it is used. If you've just described a snowflake, you could discuss the process by which it formed.
Sources of Description
When you write a description, you need to think about the kinds of descriptive detail you can provide. Sometimes, descriptions are rather weak in this area. Use the following list to plan your description or to review a description you have written. Think of the categories of descriptive detail you could provide, or use the following list to identify categories you have not used:
methods of attachment
In descriptions, you'll probably find yourself puzzling over how to handle numbers, abbreviations, and symbols:
Remember that technical writing breaks some of those rules you worked so hard to learn in past writing classes. In the technical writing context, we are often vitally concerned about numbers and want them to stand out. This concern means that you should use numerals in running text when the number indicates an exact, measured, or measurable amount or when it represents a critical value. For example, in these sentences, it seems to matter that the numbers are exact:
The cup is 3 inches in diameter. Use 4 tacks to fasten the poster to the wall.
However, this does not mean using numerals for indifferent values. For example, in this sentence, there is nothing heart-stopping about how many sections the report has: The report contains four major sections.
Anatomy of a descriptive paragraph
Typically, it starts with some statement about the purpose or function of the part, with the descriptive detail following. Descriptive detail draws upon the "sources" of description—such things as color, shape, width, and height.
In technical writing, we expect to see abbreviations. Use them in your description freely. Remember the rule on punctuating abbreviations—punctuate them only if they spell a word (for example, "in."). Remember too that abbreviations do not go up against the number they are used with (for example, make that "8 mm tape" or "8-mm tape" but not "8mm tape").
The most common problem with symbols in instructions and descriptions has to do with inches and feet. If you're writing instructions for a carpenter's dream project where there are feet and inches all over the place, use the symbols " (inches) and ' (feet). However, if you cite inch and foot measurements only a few times, use the word or abbreviation instead.
Graphics and Format in Descriptions
In most descriptions, you'll need at least one illustration of the thing you are describing, with labels pointing to the parts.
In descriptions, you'll want to use headings and subheadings to mark off the discussion of the individual parts or characteristics. Remember that, ideally, you want to describe each part in a separate paragraph or section—and flag that discussion with a heading. If you have a background section, use a heading for it too.
Lists are not nearly so important in descriptions as they are in instructions. However, if you itemize parts or subparts or list specifications, these are good situations for lists.
In descriptions, there is nothing like the important role for special notices as there is in instructions. After all, if it really is a description, readers should not be trying to follow any procedure, and, therefore, should not be running any risks of damaging equipment, wasting supplies, screwing up the procedure, or injuring themselves or others. However, you may find the note special notice to be useful to emphasize important points or exceptions.
What's it like—what's it not like?
Another important information structure often used in technical writing is comparison.
What Is Comparison?
In technical writing, comparisons can be very important. Short comparisons to similar or familiar things can help readers understand a topic better; comparisons can also help in the decision process of choosing one option out of a group. An extended comparison, which is the focus in this chapter, is one or more paragraphs whose main purpose and structure is comparison. One type of comparison is the analogy, which is a special type of extended comparison of an unfamiliar thing to a familiar thing.
Extended comparisons can be informative or evaluative. An informative comparison seeks to compare the topic to something similar or familiar to help people understand the topic or, in some cases, to help people understand both better. An evaluative comparison seeks to recommend one or more of the options by comparing them.
How to Identify Points of Comparison
When you write an extended comparison, you must start by identifying the specific ways in which you are going to compare the things you plan to write about. These points of comparison are like categories of comparative detail. For example, in an evaluative comparison of smart phones, you'd probably want to compare the best four or five machines according to the following:
- ease of use
- special features, and so on
If you don't start by identifying the points of comparison, your comparison can become uneven—for example, you might say that model 1 is easy to use but not say anything about the the ease of use of models 2, 3, or 4.
How to Organize Comparisons
One of the most important concepts to learn in writing comparisons has to do with organizing the contents. There are two basic ways to organize a comparison:
- whole-to-whole approach
- point-by-point approach
To get a sense of how these two approaches work, take a look at the following illustration of these two approaches. In the whole-towhole approach, details about each of the options being compared are lumped together. This is our natural tendency—however, it does a sloppy, uneven job of stating the comparisons. The better way is to use the point-by-point approach. In the schematic diagram in the illustration, you'd have one paragraph comparing the costs of Models A, B, and C; then another paragraph comparing the warranties of the three models; and so on.
Use the point-by-point approach unless something about your topic, purpose, or audience dictates otherwise. With the whole-towhole approach, the comparison is often uneven—you might forget to tell about the warranties for Model B; you might neglect to state the actual results of comparison—that Model C is better in terms of special features. In the whole-to-whole approach, writers often leave the actual comparisons up to the reader, thinking that just supplying the raw data is enough.
In the point-by-point approach, each of the comparative sections should end with a conclusion that states which option is the best choice in that particular category of comparison. Of course, it won't always be easy to state a clear winner—you may have to qualify the conclusions in various ways, providing multiple conclusions for different conditions.
How to Write Comparisons?
As with causal discussions, comparisons are not distinctive because of a certain kind of content. Instead, it's the special transitional words that make comparative writing work: for example, "similar," "unlike," "more than," "less than," and other such words that draw readers' attention to comparisons and highlight the results of the comparisons. Notice how many are used in the illustrations in this chapter.
When you write comparisons, take special care to use these transitional words. Emphasize the similarities and differences—don't force readers to figure them out for themselves.
Remember that this is just a typical or common model for the contents and organization—many others are possible.
How to Format Comparisons?
Comparisons don't call out for any special format; just use headings, lists, notices, and graphics as you would in any other technical document.
What are its categories—into which does it fit?
Another important information structure often used in technical writing is classification.
What is Classification?
In some technical reports, certain paragraphs or sections use a kind of writing and pattern of organization known as classification. Classification means either (1) explaining which class a thing belongs to or (2) dividing a group of things into classes. You may find that classification is an effective way to present background information to your readers.
You are "classifying" (in the strict dictionary sense of the term) when you place an object, action, or person in one of several classes. For example, the XYZ Corporation may have just come out with its new ABC computer but cannot decide whether to classify it as a laptop or a notebook computer. A botanist may have discovered a new species of fungus and must now decide how to classify it. Written documents on these questions would resemble comparison because features of the new item (the computer or the fungus) must be compared to those of the established classes. The Jupiter example in the following shows an example of a true classification in which the writer shows why the object belongs to one specific category.
Classification can also refer to breaking a thing down into its types, classes, categories, or kinds and then discussing each one. For example, computers for some time now have been divided into several classes: minicomputers, microcomputers, and macrocomputers. And, if you have ever taken biology, you know that terrestrial life is divided into into plant and animal "kingdoms"; the kingdoms, broken down into phyla (the plural of phylum); phyla, into classes; classes, into families; families, into genera; and genera, into species. Each of these divisions—except perhaps the last—represents a grouping of types.
Several key words indicate that classifications are being discussed: classes, kinds, types, categories, sorts, or groups. Classification can be quite useful in technical reports: it breaks the discussion of a subject into smaller chunks, and it can make the job of evaluation and selection much easier.
Jupiter can be classed as a Jovian planet because of its size and its average density. Indeed Jupiter is the largest planet in our solar system (as shown in Figure 16) and one of the brightest objects in the sky, having attained a magnitude of -2.5, more than a full magnitude brighter than Sirius, the brightest star in the sky. Jupiter's brightness results from its great size of course but also from its high reflectivity: it reflects about 44 percent of the light it receives. The size and composition of Jupiter's interior are open to much speculation. Some astronomers picture the interior as having a radius of over 30,000 miles and as possibly being composed of liquid hydrogen. The core is small and dense and may contain iron silicates. The other Jovian characteristic of the planet is its density. Even though its diameter is only 11 times that of the Earth, its total volume is 11 × 11 × 11, or over a thousand times that of Earth.
In this example, the writer argues that Jupiter should be categorized as a "Jovian"-type planet. This is one type of classification; in the other, you divide a collection of things into categories, or types.
How to Identify Classes and the Principle of Classification?
Once you know what you are going to divide into classes, your next step is to identify the classes and the principle of classification. For example, if you were classifying dialysis machines (used to treat people with kidney disease), you might list these classes:
- parallel flow design dialyzers
- coil design dialyzers
- hollow-fiber capillary dialyzers
The principle of classification is the design of the structure through which blood is filtered.
The principle of classification then is the method you use to sort the items into classes. If you sorted marbles into red, green, and blue ones, you'd be using color as the principle of classification. You must be careful to use only one principle of classification at a time. For example, you couldn't sort your marbles by color and size—you might have some big red ones and some small red ones!
Here are some additional examples of classifications and their principles:
|Topic||Classes||Principle of classification|
Pathway of electrical current
Main cause of the anemia
|Hurricane track prediction methods||
Total climatology and persistence methods
Particular climatology and persistence method
Circulation and climatology method
Dynamic model method
Combination of hurricane characteristics
Interaction between the wind and propeller blade
How to Discuss the Classes?
When you write the discussion of the individual classes, you must choose sources of discussion that enable you to explain each class fully, add comparisons so that readers can see the differences between the classes, and plan for the length of your classification.
Choosing sources of discussion.
Writing the discussion of individual classes is much the same as it is with extended definitions: you combine a variety of sources to explain the classes fully. To discuss the three types of dialysis machines for victims of kidney disease, you might use these sources:
|Classification of dialysis machines|
|Description||Main components of the different dialysis machines|
|Process||How the different machines operate|
|Comparison||Advantages and disadvantages of these machines|
Of course, some classifications may use only one kind of writing. For example, in the discussion of different hurricane track prediction methods, the discussion would most likely be process—step by step how the methods work.
No matter which sources you use in discussing the classes, comparison is an important ingredient. It helps readers distinguish the different classes from each other. Check out the following example of how comparisons work in classifications.
Comparing the types to each other gives readers a clearer sense of the types as well as their distinguishing features.
Short and extended classifications.
In short classifications, an overview of the types is packed into one sentence or into one paragraph. In an extended classification, you might have one or more paragraphs on each type. For an extended classification, you'll use a paragraph or more to discuss each of the classes, and a separate paragraph to introduce these classes—as illustrated in the extended classification in the following.
How to Format for Classifications?
Classifications don't call out for any special format; just use headings, lists, notices, and graphics as you would in any other technical document. For details, see:
What happened—why did it happen?
Another important information structure often used in technical writing is the discussion of causes and effects.
What Is a Cause–Effect Discussion?
Discussions like these answer questions such as the following:
- What are (or were) the causes of this? How and why does (or did) this happen?
- What brought about a situation, problem, or accident?
- What are (were or will be) the effects, results, or consequences of this? What will happen if a certain situation or problem continues?
- How does this work? What causes this to function as it does?
- Why won't this thing work? What's wrong with it?
- What changes will occur if a certain plan or action is taken?
- How can a certain problem or situation be avoided?
- What are the advantages, benefits, or disadvantages of an action or object?
- What are one or more potential solutions to a problem?
- What causes tornadoes? What sorts of damage do tornadoes cause?
- What will happen if the world continues to use petroleum resources at its current rate?
- What were the causes of the Great Depression?
- What are the effects of an economic recession?
- How does a photocopier work?
- What makes a microwave oven work? (Does this sound like your seven-year-old?)
As you can see from these examples, we can discuss the causes and effects of human or social processes, natural processes, mechanical or physical processes, historical or economic processes, meteorological or biological processes, and on and on.
If you think about it, there's not much difference between process discussion and causal discussion. Both occur over time; steps in a process often involve causes and effects. The distinction depends on your purpose and emphasis: process discussions are primarily concerned with how an event occurs; causal discussions, with why an event occurs. Process discussion focuses on the chronology of something; causal discussion focuses on the causes and effects.
- I can tell you step by step how to take a photo or what events occur inside the camera when you take a picture—that's process.
- But I can also explain to you what physical and chemical principles are at work when you take a photo, what principles actually enable you to take a photo—that's causal discussion.
For some topics, however, such as explaining tornadoes, it's almost impossible to make a distinction. Here are some contrasting examples:
|Subject||Process discussion||Causal discussion|
|Lightning||How to safeguard home appliances from lightning||What natural phenomena cause lightning|
|Instruction writing||How to set up understandable instructions||What causes instructions to be unclear|
|Acquisition of language by children rapidly||How to help children learn language more rapidly||Why certain children learn language more rapidly|
|Growing tomatoes||How to plant and care for tomatoes||Reasons why tomatoes are less productive|
|Air conditioning||How cool air is produced by conventional systems||Why your air conditioning is costing you more this summer|
Here are some common reasons why you may need to discuss causal and effects:
- You need a record of the damage done by something. Photographs work, but words may also be needed.
- You need an account of the scientific principles at work in a process so that you can understand what you are doing in an instructional procedure.
- You need to understand the causes of something so you can have a better understanding of how to control or eliminate it.
- You need to understand the effects of something so that you can work to prevent it or increase its likelihood.
How to Organize Causal Discussions?
How you organize the contents of a causal discussion depends on how many and what combination of causes and effects you discuss:
- Single cause–single effect—A single cause can lead to a single effect; for example, a radiator leak can cause the car to overheat.
- Multiple causes–single effect—Many different causes can be seen as leading to one effect: for example, high unemployment, high interest rates, and high real estate costs (causes) might lead to decreased real estate sales (effect).
- Single cause–multiple effects—A single cause can be seen as producing numerous effects. For example, proponents of the greenhouse effect believe that increased CO2 in the atmosphere (cause) will lead to changes in weather patterns, higher temperatures, drought, increased storm activity, and higher sea levels (effects).
- Sequential causes and effects—One cause can bring about an effect, which in turn becomes the cause of another effect, and so on. For example, proponents of the greenhouse effect argue that increased burning of fossil fuels (cause) leads to increased CO2 in the atmosphere (effect) which in turn is the cause of less thermal energy being reradiated out of the system (effect) which in turn becomes the cause of increased global temperatures.
- Alternate causes and effects—Causes and effects can be alternating. For example, if the car won't start (effect), it may be because of a dead battery (alternate cause 1), no gas in the gas tank (alternate cause 2), or a faulty part (alternate cause 3).
Consider a simple example: imagine you want to discuss how a single situation has led to a number of problems, in other words, one cause leading to several effects. In a single paragraph, the first couple of sentences might focus on the cause; each of the following sentences would focus on the effects. In an extended discussion, there might be a paragraph on the cause, and a paragraph on each of the effects. The preceding schematic diagram of a causal discussion in shows you how the single-paragraph approach would look.
How to Discuss Causes and Effects?
Actual discussion of causes and effects is not as immediately identifiable as descriptive or process writing are. Typically, causal discussions talk about events and describe things. What makes causal discussions distinctive is the use of transitional words to indicate the causes and effects.
In this sentence:
Increased deficit spending by the government leads to increased inflation
the verb "leads to" establishes the connection between a cause and an effect. In this excerpt, the connective "consequently" establishes a causal link between the increasing domestic anger over the Vietnam war and Johnson's decision not to seek reelection:
Meanwhile at home, anger, hostility, and outright revolt against the war grew. Johnson, sensing he could not get reelected in this atmosphere, consequently decided against running for another term.
How to Format for Causal Discussions?
Here are a few suggestions on format as they relate specifically to causal discussions:
- Headings. If you write an extended causal discussion and have separate paragraphs for each of the causes or effects, then the headings should signal those causes. (See the examples in this chapter.)
- Lists. If you discuss sequential causes and effects, you're likely to need in-sentence and vertical numbered lists. If you have multiple causes or effects but no necessary order amongst them, then bulleted lists are appropriate.
- Graphics. Causal discussions often use conceptual diagrams to show the relationships between the causes and effects. In these you give a spatial representation of the causes and effects as they occur in time.
- Style. As with any other technical writing, you treat numbers, symbols, and abbreviations in process discussions the same. Exact measurement values should be numerals, regardless whether they are below 10.
How can you define it?
An important writing tool you'll need, particularly if you are writing for nonspecialists, is definition—or more specifically, extended definition. An extended definition is a one or more paragraphs that attempt to explain a complex term. Some terms may be so important in your report, there may be so much confusion about them, or they may be so difficult to understand that an extended discussion is vital for the success of your report.
When you write reports, you may often discover that you need to explain certain basics before you can discuss the main subject matter. For example:
- In a report on new treatments for sickle cell anemia, you'd need a section defining the disease.
- In a report on the benefits of drip irrigation, you'd need to write an extended definition of drip irrigation, explaining how it works and what equipment is used.
- In a report showing small businesses how to weather economic recessions, an extended definition of the term economic recession would be needed first.
Writing Formal Sentence Definitions
One of the first things to do when you write an extended definition is to compose the formal sentence definition of the term you are writing about. Place it toward the beginning of the extended definition. It establishes the focus for the rest of the discussion. It is "formal" because it uses a certain form. Here are several examples:
Take particular care when you write the reference to the class to which the term belongs; it sets up a larger frame of reference or context. It gives readers something familiar to associate the term with. The term may belong to a class of tools, diseases, geological processes, electronic components; it may be a term from the field of medicine, computer science, agriculture, reprographics, or finance. Avoid vague references to the class the term belongs to: for example, instead of calling a concussion an "injury" or botulism a "medical problem," call them something more specific like "a serious head injury" and "a severe form of food poisoning," respectively.
Similarly, provide plenty of specific detail in the characteristics component of the formal sentence definition. Readers need these details to begin forming their own understanding the term you are defining.
Be aware, however, that your formal sentence definition will likely contain additional potentially unfamiliar terms. Somewhere in your extended definition, you'll need to explain them as well, possibly by using short definitions (explained later in this section).
Choosing the Sources of Definition
When you write an extended definition, you literally grab at any of the writing resources or tools that will help you explain the term to your readers. This means considering all of the various sources of information that can help define the term adequately (for example, description, process narration, causal discussion, and classification).
Notice how many different kinds of writing are indicated in the examples in this chapter.
The key to writing a good extended definition is to choose the sources of definition to help readers understand the term being defined. Use this checklist to select the kinds of discussion to include in your extended definitions:
Adding Short Definitions
As mentioned earlier, you'll find that in writing an extended definition, you must define other terms as well. Typically, short definitions—a sentence, clause, or phrase in length—will suffice. Notice how many are added to the "after" version in the following.
This process of supplying short definitions "on the fly" is critical in good technical writing for nonspecialists. Notice how many quick definitions occur just in the first two sentences of the preceding illusration. "Maculopapular" is defined in parentheses as "(raised red)." "Endemicity" is defined by restating the idea in other words: "that is, people throughout the world are capable of contracting measles." And "infective particle" is quickly defined by providing an alternative: "or organism causing the illness." Obviously, the passage is almost tripled in length—but that's the price for thorough explanation and clarity.
Format for Extended Definition
Extended definitions don't call out for any special format; just use headings, lists, notices, and graphics as you would in any other technical document:
How does it happen?
In technical writing, process discussion is one of the most important kinds of prose: people need to know how things happen, how things work, how to operate things, and how to perform certain actions. A narration tells how something occurs over a period of historical time. A process is an event or set of events that can be performed or that occurs regularly or repeatedly. The words "procedure" and "routine" are closely related. When you "narrate" a "process," you explain how something works or how something occurs. We'll use "process discussion" here.
What Is a Process?
Process discussion is an information structure—it's one of those fundamental combinations of content and organizational patterns you use in many different situations in technical writing. For example, instructions are an application of technical writing; instructions make heavy use of process discussion.
- How does this mechanism work?
- What are the typical steps in this natural, mechanical, social, biological, psychological phenomenon?
- How does this event (mechanical, natural, human, social) happen?
When we ask questions like these, we expect a systematic step-by-step explanation of how the mechanism works or how the phenomenon happens. We're not looking to perform it ourselves, just to understand it. These are closely related to process discussions. In causal discussions, we're interested in why something happens, what causes it, what its results or consequences are. In process discussions, we are interested in how something happens, how it works, in a step-by-step fashion. Often the distinction between these two is blurry.
Process discussions focus on things like formation of lightning, snow, hurricanes, cold fronts, tornadoes; gestation of a human embryo; pollination of a flower; automatic operations of a photocopier or a computer; occurrence of supernova, black holes, red giants, or white dwarfs. Process discussions explain the workings of such mechanisms as automobile batteries, light bulbs, telephones, televisions, microwave ovens, stereo receivers.
As mentioned previously, the focus in this chapter is noninstructional process. However, while explaining how doctors perform open heart surgery or how a nuclear power plant operates might sound like instructions, they aren't! Normally, documents on these topics would give people an overview of what goes on in these processes. This next illustration conveys a general idea of how seawater is converted into fresh water:
How to Divide the Process into Steps?
When you write a process discussion—whether it's a single paragraph or a whole report—one of the most important tasks is to divide the process into its main steps, phases, stages, or periods. There are of course other ways to handle a process discussion, but division by steps is usually the best. For example, you might try organizing a process discussion by the key parts of a mechanism. Use whichever plan seems to work best for your readers, topic, and purpose.
A step is one action or event (or a group of related ones) that is performed or that occurs in the process. Consider a simple process such as making coffee with a drip coffee pot. Such an activity involves the following steps, each of which actually represents a group of actions:
- Boiling the water
- Finding the kettle and taking it to the sink
- Turning on the water and rinsing out the kettle
- Filling up the kettle to the desired amount
- Turning off the water and walking to the stove
- Placing the kettle on a burner
- Turning on the burner
- Waiting for the water to boil
- Rinsing the coffee pot and the basket
- Measuring in the new coffee
- Pouring in the boiling water
Obviously, no one needs to be told all these specific actions; the example shows that a step usually stands for a group of related specific actions or events. If you look back at the preceding desalination example, you see a more realistic example of this process of division into steps. The discussion focuses on four steps in the desalination process: (1) pressurization and evaporation, (2) freezing, (3) separation, and (4) discharge of the briny portion of the seawater.
How are process discussions used in technical documents? First and foremost, processes are typically explained in instructions. For some situations, explaining how a thing works is almost as effective as providing the direct step-by-step instructions. And in any case, people understand the actions they are performing better when they understand the actions behind those actions. Process discussions are also vital in new product documents—either internal (meant for the product's designers and marketers) or external (meant for the product's customers and users). And finally process discussions are important in scientific research literature. You can imagine researchers studying acid rain or oil spills—understanding these processes might lead to controlling them better.
How to Discuss the Steps?
When you discuss a process, your goal is to enable readers to understand how that process works, the typical events that occur in that process. You use any writing tools at your disposal to accomplish that end. One of the most common ways of explaining a process is to divide it into steps, phases, periods, stages. These are essentially time segments—groupings of closely related events or actions. Take a look at any of the examples in this chapter; you'll see process sentences everywhere.
However, most process discussions aren't much without explanations of the causes and effects operating behind them. For example, it's not terribly exciting to read that when tornadoes form, it gets cloudy, wind and rain and twisters occur, wrecking things. We want more that just the bare-bones process: we want to know what causes them to form, what are the conditions favorable to their formation, how they behave once formed, and of course what sorts of damage they cause.
Other sorts of information can supplement the discussion of processes as well:
- Description: Explain how things look before, during, or after the process, or any phase within the process.
- Definitions: Explain the meaning of any technical terms used in the discussion.
- Comparisons: Compare the process, any of its phases or outcomes, to something similar or something familiar to help readers understand.
- Examples: Provide examples of the process you are explaining. For example, in a discussion of tornadoes, examples of tornadoes in history can help.
Mitosis is the process of cell duplication, during which one cell gives rise to two identical daughter cells. The process consists of four main phases: prophase, metaphase, anaphase, and interphase.
- In prophase, the genetic material thickens and coils into chromosomes, the nucleus disappears, and a group of fibers begins to form a spindle.
- In metaphase, the chromosomes duplicate themselves and line up along the mid-line of the cell. The halves are known as chromatids.
- In anaphase, the chromatids are pulled at opposite ends of the cell by the spindle fibers. At this point, the cytoplasm of the mother cell divides to form two daughter cells, each with the number and kind of chromosomes the mother cell had.
- In interphase, the daughter cells begin to function on their own, once their nucleus membranes and nucleoi reform.
Expanding example of process discussion. Information structures can work like an accordian—they can expand or collapse according to your needs.
How to Format Process Discussions?
Here are a few suggestions on format as they relate specifically to process discussions.
- Headings. If you write an extended process discussion and structure it by steps or phases, in other words, time segments, then the subheadings can be related to those steps or phases, as illustrated in the following schematic view of process discussions. If your process discussion has one section in which you explain the process and another in which you discuss some supplementary aspect of the process, your headings would need to indicate that structure as well.
- Lists. Because they focus on sequences of events, process discussions are likely candidates for in-sentence and vertical numbered lists as the examples in this chapter show.
- Graphics. Process discussions are prime territory for flow diagrams such as you see in some of the illustrations in this book. In these you give a spatial representation of things as they occur in time. Useful also are diagrams and drawings of the mechanisms that take part in the process.
- Style. You treat numbers, symbols, and abbreviations in process discussions the same as in any other technical document. Exact measurement values should be numerals, regardless whether they are below 10.
Tell them why—get them on your side
When the teaching of technical writing first emerged in university engineering schools, it was defined as rigorously objective in writing style—even to the extent of using the passive voice instead of the first person singular "I." The standard model was the primary research report. However, since then, it has become clear that technical writers must often engage in persuasive communication efforts in their primary work.
What Is Persuasion?
The infrastructure essential in proposals and progress reports is persuasion. To convince people to hire you to do a project and to reassure them that the project is going well, you need persuasive strategies. This chapter reviews the common persuasive strategies to get you ready to write those kinds of documents—as well as persuasive technical documents. Understanding general persuasive writing strategies, you will be well-equipped to develop these kinds of documents:
- Application letters
- Progress reports
- Complaint letters
Persuasion is the communicative effort to convince people to think a certain or act a certain way—to vote for a city-wide recycling program, to oppose the building of more coal-fired electricity plants, and so on—or the opposite!
In the view of some, persuasion is not a legitimate tool for technical communication. For them, technical writing is supposed to be "scientific," "objective," "neutral." However, if you grant that proposals, progress reports, resumes, application letters, and even complaint letters are instances of technical communication because they often must convey technical information, then you see that persuasion is an important tool in technical communication.
What Are the Tools of Persuasion?
The classical approach to persuasion, laid down my Aristotle (384–322 BCE) in the Art of Rhetoric, involves these appeals to readers and listeners (remember your Rhetoric and Composition 101?):
- Logical appeal—When you use reasons and arguments, backed up by facts and logic, to make your case, you are using the logical appeal. We normally think of the logical appeal as the only legitimate method of argument, but the "real world" shows us differently.
- Emotional appeal—When you attempt to rouse people's anger or sympathies in a persuasive effort, you are using the emotional appeal. Showing a little girl fleeing from a burning village bombed by war planes or an oil-soaked seagull on a beach devastated by an oil spill—these images spark emotions like anger, horror, sympathy; but they don't make a logical case for or against anything. These images may, however, capture readers' attention and cause them to pay more attention to the rest of your persuasive effort.
- Personal appeal—When you present your qualifications, experience, expertise, and wisdom or those others, attempting to build readers' confidence, you are using the personal appeal. As with the emotional appeal, there is no logical justification for the personal appeal. It's like saying, "Trust me." Despite that, readers sometimes want to know who you are and what gives you the right to speak so authoritatively on the subject. Just as the emotional appeal can be used legitimately to get readers to pay attention and care about your message, the right amount of personal appeal can build readers' confidence in you—or at least a willingness to hear you out.
You may also have encountered the "stylistic" appeal: the use of language and visual effects to increase the persuasive impact. For example, a glossy, fancy design for a resume can have a positive impact just as much as the content.
In your rhetoric and composition studies, you may also have encountered something called the Toulmin approach to persuasion. The complete system involves claims, grounds, warrant, backing, and rebuttal, but a particularly useful element is the rebuttal, and another known as the concession.
- Rebuttal. In a rebuttal, you directly address counter-arguments that your persuasive opponents might bring up. You show how they are wrong or, at least, how they don't affect your overall argument. Picture yourself face to face with your persuasive opponents—what arguments are they going to come back at you with? How are you going to answer those arguments? In a written persuasive effort, you must simulate this back-and-forth, debate-style argumentative process. Imagine your opponents' counter-arguments (arguments they might put forth against your position) and then imagine your own rebuttals (your answers to those counter-arguments).
- Counter-argument. A persuasion can be structured entirely around tearing down the opponent's argument. Consider this example:
- Concession. In a concession, you acknowledge that certain opposing arguments have some validity, but you explain how they do not damage your overall argument. Concessions build personal appeal: they make you seem more open minded.
- Synthesis. Modern rhetoricians urge us not to view the persuasive process as a win-lose, all-out war. When people are entrenched, they shut out the arguments of the other side. Such rigidity prevents us from resolving the issue and getting on with our lives. Instead, the process of counter-argument, rebuttal, and concession should be sincere and continuous until all parties reach synthesis—a middle ground where they drop their weapons and agree.
What Are the Common Flaws in Persuasion?
You should be aware too of the logical fallacies commonly found in persuasive efforts:
- Hasty generalizations. When you draw a conclusion based on too little evidence, that's a hasty generalization. For example, if you conclude that there is a big social trend to return to the 70's look because you see two or three bellbottoms and paisley shirts one day, you've drawn a hasty generalization based on a very limited, incomplete sample.
- Irrelevant, ad hominem arguments. When you base all or part of your persuasive effort on your opponent's character, behavior, or past, that's an ad hominem argument (meaning "to the man" in Latin). If a middle-aged political candidate were attacked for smoking marijuana in college, that might be an irrelevant personal attack.
- Bandwagon effect. If you base all or part of your persuasive effort on the idea that "everybody's doing it," you're using the bandwagon effect. Commercial advertisement commonly uses this tactic: everybody's buying the product—so should you!
- False causality. If you argue that because one event came after another, the first event caused the second, you may be making an argument based on false causality. For example, imagine that your father joined IBM in 1984 as a low-level regular employee and shortly thereafter the company began its historic slide to near-extinction. Imagine further that in 1995 he left the company, at which time the company began its remarkable comeback. Was it your dad who nearly brought the company to its knees? Did his departure save the company?
- Oversimplistic, either–or arguments. If you reduce the choices to the one you favor and to a totally unacceptable one, you are using an oversimplistic, either–or argument. Advocates of the nuclear power plant might argue that either we build the thing or we go without electricity.
- False analogies. When you compare a situation to a simple object or process, that's an analogy. When you base an entire persuasive effort on an analogy, you may have problems. Some analogies are just wrong to begin with. And, at some point, all analogies break down. For example, arguments relating to global warming often use the analogy of how a car heats up when the windows are rolled up. The Vietnam war was justified using the analogy of how dominoes all topple over when they are lined up. Analogies can help readers understand, but not justify an argument.
How to Write a Persuasive Document
Here are guidelines on writing persuasively in a technical-writing content:
- Carefully pick your topic and your approach to it. Finding a project for persuasion is like trying to pick a fight. Think of the main issues of the day—global warming, ozone-layer depletion, alternative fuels, mass transportation, pesticides, zero population growth, solar energy, cloning (bioengineering), abortion, effects of computer- and video-game violence, capital punishment, nuclear armaments, chemical warfare. Each of these topics has multiple issues that are hotly debated. Technical-writing courses are not the place for the common pro-and-con and letter-to-the editor essays you may have written in past writing courses. However, these topics have a technical side that challenges your abilities as a technical writer. What are the logical arguments for recycling——more specifically, a city-based curb-side recycling program? They range from altruistic (for the city, for the planet) to selfish (to reduce waste management costs, to decrease taxes). Which arguments you use depends on your readers. Altruistic arguments may be of no use to certain conservative or business readers or to city administrators, but they may be vital in getting ordinary citizens to back such the program.
- Define each of your arguments; plan how you will support them. You must prove each logical argument, using supporting data, reasoning, and examples. You can't just baldly state that something costs less, works better, provides benefits, and is acceptable to the public—you've got to prove it! In your persuasive effort to get the city to consider recycling, you might use the logical appeal that such a program would reduce landfill requirements. How can you prove that? Do some research. What's the city's daily input to the landfill; what are the costs? Can you determine the percent made up by recyclables? If you can get believable numbers, calculate landfill savings in terms of volume and dollars.
- Consider emotional appeals. At best, emotional appeals capture readers' attention and get them to care about the issue. At worst, they rouse strong emotions such as fear and anger, preventing readers from thinking clearly about the issue. What emotional appeals could you use for the recycling promotion (not that you actually would, of course)? Images of overflowing landfills might work; images of dwindling natural habitats, replete with deer, chipmunks, hummingbirds——these might work. Would they pull at the heart strings of your readers, or would readers cynically mutter "give me a break"? How would you feel about using such tactics?
- Consider personal appeals. Like emotional appeals, personal appeals have no logical relevance to an argument. If you use the personal appeal, you attempt to build readers' confidence in you as someone who is knowledgeable and reliable. Citing years of experience and education is a common example of building a personal appeal. What personal appeals could this recycling persuasion use? To get people to accept your data, cite believable sources, such as government reports or leading experts. To give yourself credibility, describe your past experience and training in this area. Perhaps also describe yourself as a long-time resident of the city. These appeals shouldn't have any relevance, but they may cause people to hear you out.
- Address any counter-arguments. It's a good idea to address counter-arguments—objections people might raise in relation to your argument. Imagine people out there saying "but—but—but—!" Discuss their counter-arguments and show how they are wrong, how they can be addressed, or how they are irrelevant to your main point. Notice that the persuasive document advocating recycling is structured on counter-arguments: Recycling: Not a Waste of Money or Time! As for recycling programs, you must address the standard objections. It's a hassle. Your might counter-argue that recycling is no more of a hassle than taking out the garbage. It's a hassle sorting everything and keeping in separate bins. That one is easy——most recycling programs don't require sorting. It's messy and attracts pests. Hmmm, that's a hard one——time for some research.
- Plan an introduction. In an introduction to a persuasion, you cannot start out guns blazing and swords rattling. It's not necessary to state your main argumentative point right away. Instead, just indicate the subject matter—not your main point about it. Your readers are more likely to hear you out. Imagine that you've written the main sections of this persuasion. You have logical appeals, counter-arguments, and possibly some personal and emotional appeals as well. Instead of demanding that the city adopt a recycling program, begin with a quiet purpose statement that this document "looks at" or "investigates" the possibilities for recycling. Indicate that this document is for both city officials and ordinary citizens. Provide an overview, indicating that you'll be discussing current and projected landfill use and associated costs, amount of recyclables in municipal waste, their recyclable value, potential revenue from a recycling program, costs of a recycling program, and necessary administrative and citizen participation in such a program.
- Consider the conclusion. In a persuasion, the final section is often a "true" conclusion. If you have not yet overtly stated your main argumentative point, now's the time. When you do, summarize the main arguments that support it. While the introduction may be the place for quiet understatement, the conclusion is the place to pound home your main point. Come out and state vigorously that the city should implement a recycling program and then summarize the main reasons why.
How to Format Persuasive Documents?
Here are a few suggestions on format as they relate specifically to persuasive documents.
- Headings. If you structure your persuasion by individual arguments, then the subheadings can be related to those arguments. Notice that the headings in the example persuasion address the counter-arguments: Recycling: Not a Waste of Money or Time!
- Graphics. Factual information—data—supplies a great deal of the legitimate support for your presuasive effort. Make that data more dramatic and vivid by creating tables, charts, and graphs. Graphics—illustrations, drawings, photos—can also supply that essential logical support—but also the emotional support mentioned earlier.