Online Technical Writing:
Power-Revision Techniques—Structure-Level Revision

For lack of a better phrase, "structure-level revision" refers to the techniques you can use to improve the content of a document, make it better organized, and facilitate readers' ability to follow and understand it. At this level, we're not tinkering with commas or subject-verb agreement—we're tossing around whole paragraphs, adding whole new sentences, deleting chunks of useless text, reorganizing sections, and adding various kinds of signals to make things easier to follow.

Specifically, this section on structure-level revision techniques covers the following:

• Contents
• Structure
• Organization
• Topic sentences and overviews
• Transitions

One of the most important ways you can review a rough draft is to check the contents. All the good transitions, good organization, and clear sentence structure in the world can't help a report that doesn't have the right information. Information in a report can be "wrong" in several ways:

• It can be missing altogether: for example, imagine that somebody wrote a report on "virtual communities" but never bothered to define what that term means. It would be tough going from the start of that report.
• It's there but not enough of it: take the same example—imagine that the writer only made a few vague statements about virtual communities. What was needed was at least a paragraph on the subject, if not a full-blown 3- or 4-page section.
• It's there but at the wrong level for the audience: It's also possible to pitch information at the wrong level in terms of readers' knowledge, background, or needs. Imagine that the writer did include a 3-page section on data caching but written for the product developer (an "expert" audience) when the report was really intended for nonspecialists.

If you can get a sense of how information is inadequate in a report rough draft, you should be well on your way to knowing what specifically to do to revise. One useful brainstorming tool is to think in terms of types of content. Use the following questions to review your rough draft for the types of information to add or change:

• Definitions—Are there key terms in your report that need to be defined? Is one of those terms so important that it needs a full section for adequate definition? Most terms can be defined in a sentence or two at the point they first occur, but some terms may be so important to the report and so complex that they need a whole section (one or more paragraphs) to define.

• Description—Are there objects, mechanisms, places, animals, even people that need to be described? If you are comparing different models of some sort of new equipment, should you describe them physically first? Can you divide the thing into parts, components, or characteristics and describe each separately? Consider whether to work this description into the existing discussion or to make it its own separate section. (See the chapter on writing descriptions .)

• Process discussion—Are there processes in your report that you should discuss in detail? They may be either natural processes (those occurring in nature) or human-controlled processes (those that are initiated, controlled, or performed by people). Again, as with description, you may be able to work this extended process explanation into the existing discussion, or you may want to put it in a separate section of its own. (See the chapter on writing process discussions .)

• Comparisons—Would comparison to similar or more familiar things be helpful? Would analogies help—extended discussion of similarities between your topic and something familiar (for example, by comparing a computer to a typewriter)? Are evaluative comparisons needed in your report—in other words, comparisons that lead to a decision or recommendation? (See the organizational approach to comparisons.)

• Division into categories—Are there subcategories associated with your topic? Would discussing them improve your discussion? Consider an extended discussion of the categories—with an introductory paragraph that explains the principle of the classification then separate paragraphs on each of the categories. (See the chapter on writing classifications.)

• Location within a category—Would it help readers to understand your discussion better if you located the topic in one of several categories (for example, by discussing whether some new computer model is a laptop, notebook, or subnotebook)? (See the chapter on writing classifications.)
• Causal discussion—Should you include an extended discussion of the causes of some situation related to your topic? Should you include an extended discussion of the effects (consequences, results) of some situation related to your topic? If you use the extended approach, see whether you can separate the discussion of each cause or effect into a section of its own. (See the chapter on writing causal discussions .)

• Examples—In technical discussions, examples are almost always in order. Examples can be worked into the existing text, or you may want to see about creating a separate section for extended discussion of an example.

• Analogies—Analogies, as mentioned above, are extended comparisons. You compare your technical topic to something very familiar (for example, a computer to a typewriter—although how familiar is the typewriter any more?).
• Historical background—Can you discuss the history, people, events related to your topic? Would this discussion help readers better understand your discussion or help you better achieve your writing purpose?

• Instructions—Are readers looking to your report for instructions on building, assembling, operating, or repairing something? If so, use the standard format for instructions as discussed in the instructions chapter.

• Narrative—Is there some event associated with your topic that needs to be discussed. Narrative is different from process discussion, mentioned earlier: narrative discusses a one-time series of events; process discusses a routine, repeated, or repeatable series of events. If you do need to include narrative, consider putting it in its own separate section.

• Content based on typical reports—One other way to brainstorm about the contents of a report is to review the typical contents of the type of report you are writing. For example, if you are writing a laboratory report, there are certain expected contents—make sure you've included them, or at least the ones that apply.

There are two ways of looking at the organization of information in a document: one, covered in the next section, involves looking at the sequence of chunks of information, seeing if they are in the right order. Another has to do with levels of information. You can look at the sentences or paragraphs in a rough draft and see that some sentences go to a deeper level of discussion on the topic than others. Other sentences act like the framework upon which those deeper-level sentences depend. By looking at structure in this way, you not only check its organization but also get a lot of good ideas about how to improve the content of the text.

In the flow of writing, sentences either go to a deeper level of detail or add detail at the same level. For example:

		I have a 1982 Peugeot parked in the driveway.

Lower level	It has 112,000 miles on it.

The second one comments, or goes to a "deeper" level of discussion on the first. Others stay at the same of detail. For example:

		I have a 1982 Peugeot parked in the driveway at home.

Same level	Inside my home, I have a 386-SX computer.

These two are at the same level of detail—they seem to itemizing the stuff I own but not making any further comment on any of it. You can view your writing in these structural terms at any level. Instead of sentences, you can think in terms of paragraphs, whole groups of paragraphs, or even large sections of writing.

How can you use this kind of structural view of your writing? First, it is obviously a good way to check for organization. More powerfully, however, this approach enables you to sense what else you might say about your topic. Once you've got a sense of the structure of the sentences, paragraphs, or sections, you can start asking yourself "should I add more same-level detail here?" or "should I add deeper-level detail here?" You're likely to find spots where you could have said more, making your discussion more complete and explanatory or convincing or whatever purpose it was trying to accomplish.

If you have the right information in a report, at least you've got all the "right stuff" available for readers. However, it may still not be adequately organized—like when you've just moved and everything is a mess or still in boxes. You need two essential skills for reviewing the organization of a rough draft:

• Identifying the topic of chunks of information at various levels. To assess the organization of a string of paragraphs, you start by thinking of a word or phrase to identify the topic of each paragraphs—in other words, get a handle on each one. Then you stand back from those words or phrases, considering whether they are in the right sequence. However, that's only one level. You can also look within an individual paragraph for its organization. In this case, you identify the topic of each sentence and consider the sequencing of those sentences.

• Choosing the best sequence for chunks of information. Once you know the topic of each of the chunks of information (at whatever level you are investigating), then you can decide whether they are in the right sequence. This decision involves knowing the common sequencing patterns; here are some examples:
  • General —> specific: One of the most comon ways to organize is to arrange chunks of information from general to specific. For example, defining all solar collectors is a more general discussion than discussing the different types of solar collectors. And describing the operation of a specific type of solar collector is even less general. (This pattern is illustrated in Figure E-1.)

  • Simple, basic —> complex: Another way to arrange units of a discussion is to begin with the simple, basic, fundamental ones and then move on to the more complex and technical.

  • Thing-at-rest —> thing-in-motion: Another organization pattern involves first describing the thing (as if in a photograph), then discussing its operation or process (as if in a video). This approach might work well for a discussion of a fuel-injection system.

  • Spatial movement: If you are describing the physical details of something, you might want to use some pattern of physical movement, for example, top to bottom, left to right, or outside to inside.

  • Temporal movement: One of the most common patterns is based on movement through time; arrange the discussion of events in relation to the temporal sequence.

  • Concept —> application of the concept, examples: A common organizational pattern is to discuss a concept in general terms then discuss an application of it. For example, another chapter in this book discusses proposals first conceptually then discusses examples of proposals.

  • Data —> conclusions: Another means of organizing information is to present data (observations, experimental data, survey results) then move on to the conclusions that can be drawn from that data. (And this pattern is sometimes reversed: present the conclusion first, then the data that supports it.)

  • Problem, question —> solution, answer: You can also organize information by first discussing a problem or raising a question then moving on to the solution or answer.

  • Simplified version—>detailed version: A useful way to explain technical matters to nonspecialists is to begin by discussing a simplified version of the thing, establish a solid understanding of it, then go right back and explain it all again but this time laying on the technical detail thick and heavy!

  • Most important —> least important: A more "rhetorical" method of organization is to begin with the most important, the most eye-catching, the most dramatic information first then move on to information that is progressively less so. (And this pattern can be reversed: you can build up to a climax, rather than start with it.)

  • Most convincing —> least convincing: Similarly, you can start with the most convincing argument for your position—to get everybody's attention—then move on to less and less convincing ones. (This pattern can also be reversed: you can build up to your most convincing arguments.)

Figure E-1. Revision by reorganization: it is a more natural progression to start by defining what all solar collectors do, then move on to their different types.

These are just a few possibilities. When the aim is informative, you arrange information so that you ensure that readers understand the basics before moving onto the complicated, technical stuff. When the aim is persuasive, you arrange things to maximize the persuasive effect on the readers, for example, by putting the strongest arguments first.

And in any case, you avoid mixing these approaches—for example, throwing out some data, then stating a few conclusions, and then doing this back and forth in a haphazard way. Keep the apples separate from the oranges!

Figure E-2. Revising to incorporate overviews (topic sentences). In the problem version, it's hard to know where the paragraph is headed. In the revised version, the direction is made clear from the beginning.

One of the best things you can do is go back through a rough draft and check to see if you can insert topic sentences and overviews at key points. When we write, we're not normally sure exactly where a paragraph or section is going in terms of its content and logic. Once it has "gotten there," it is often necessary to go back to the beginning and add some sort of overview or modify what's already there to make the overview clearer. Readers need to know where they are going in a report, what's coming up next, and for that matter where they've just been. Having an overview in a report is like having a map when you're in a new city. Topic sentences and overviews offer a perspective on what's where: the topic, the subtopics, the purpose of the upcoming discussion, its relation to the previous section and to the document as a whole. (Now some of this involves transitions, which is the next element to review for.)

Figure E-2 illustrates this process of going back and fixing up topic sentences and overviews. It shows you before and after versions of a paragraph.

You can have the right information in a report and have it organized properly, but something important can still go wrong. Readers can miss the "flow" of the ideas, have a hard time sensing how the chunks of information are related or connected to each other. What readers need is continuous guidance—which is what you the writer provide. And what you use to provide that guidance is called transitions—various devices that help readers along through a document. There is (or certainly should be) a logic that connects every sentence in a document and that dictates a certain sequence to those sentences.

Your sense of that logic enables you to put the various chunks of information in a report in the proper order. However, readers may have trouble at times seeing that logic. Transitions emphasize that logic. It's not that the connecting point between every pair of information chunks requires some full-blown transition—just the ones that readers are likely to have trouble getting through. Usually, as writers, we almost unconsciously supply the transitional devices that guide readers along. But sometimes we forget, or sometimes a connection that seems obvious to us is hard for readers to see. Then we need to work particularly hard to make the connection apparent.

Once you've identified problem points in your rough draft where better transitions are needed, the next step is to analyze each problem point and find the transition that will improve the connection. To do this, you need to understand something about how transitions operate and what choices you have among them. First, in principle, a transition is a signal that shows how a preceding chunk of information is logically related to a current or upcoming chunk of information. It looks backwards and looks forward at the same time. For example:

     It may be 3 a.m., but I'm not sleepy a bit

In this example, the transitional word "but" sets up a contrast between the topic of the first chunk of information (the lateness of the time) and the second chunk (my lack of sleepiness). The logic is contrastive in this case, but there are other kinds of logic. For example:

     My Peugeot has almost 112,000 miles on it. It still runs great!

In this example, the transitional word is "it," a simple pronoun. Here, the logic is additive, I'm simply adding one related thought onto another. These examples are obviously stupidly simplistic—but when you get into a complex technical topic and the chunks are whole paragraphs of information, transitions really begin to matter.

Figure E-3. Revising problems with transitions. The problem version reads like a series of disconnected statement floating in space. The revised version adds transitional devices to pull the statements together in a "coherent," flowing discussion.

People who have studied the way communication, in particular, writing, works have identified these kinds of basic logic that knit ideas together:

• Additive—One idea can be added to another; information can simply be added to other information within a paragraph. Additive transitional words and phrases include and, moreover, as well as, too, in addition to, furthermore, also, and additionally.

• Narrative, chronological, temporal—One idea can follow, precede, or occur simultaneously with another. Narrative transitional words and phrases include then, next, after, before, since, subsequently, following, later, as soon as, as, when, while, during, until, and once.

• Contrastive, comparative—Two ideas can be compared to each other to show differences or similarities. Contrastive transitional words and phrases include but, on the other hand, unlike, as opposed to, than, although, though, instead, and similarly.

• Alternative—Two ideas can act as alternatives or substitutes for each other. Alternative transitional words and phrases include either, or, nor, on the other hand, however, neither, and otherwise.

• Causal—One idea can be the cause or the result (effect, consequence, etc.) of another. Causal transitional words and phrases include thus, then, unless, subsequently, therefore, because, consequently, as a result, if, in order to/that, for, and so.

• Illustrative—One idea can be an example or an illustration of another. Illustrative transitional words and phrases include for example, for instance, to illustrate, and as an example.

• Repetitive, reiterative—To ensure clarity, an idea can be restated or repeated using other, perhaps more familiar, words. Repetitive transitional words and phrases include in other words, in short, that is, stated simply, and to put it another way.

• Spatial, physical—The things referred to by one statement can have a spatial relationship to another thing referred to by another statement. The logic connecting the two statements can be spatial in nature. Typically, prepositions indicate such logic: for example, under, beside, on top of, next to, behind, and so on.

It takes a surprising amount of brain power to construct a transition: you must know the topic of the preceding chunk of information, the topic of the current or upcoming one, the logic that connects them. Then, with that in mind, you must pick out the transitional device that you think will best guide the reader across that juncture between the two chunks of information. Scholars have identified a half-dozen or so kinds of transitional devices (but it seems like there ought to be more...):

• Transitional words—The easiest to spot are words like "but," "however," "on the other hand," "therefore," "for example," "in other word," "in addition," and so on. These specifically mark the logic as contrastive, alternative, causal, illustrative, additive, and so on, which we looked at in the preceding section.

• Repeated key words—Strangely enough, simply repeating the key word, the word that is the focus of topic of the discussion is also a transitional device—but not a very strong one of course. You can actually improve the flow of a piece of writing by working on the way you repeat the key words. As writers, for some reason, we feel compelled to vary word choice. However, this can lead to problems when it involves the main topic or subtopics. After all, if you suddenly start calling a "diskette" a "disk," people may wonder if you're talking about something different. Therefore, in a technical context, it's often a better choice to use the same words, even at the risk of sounding a bit repetitive. Where the repeated key words occur in a sentence can also affect the ease by which readers follow your discussion. If you bury the key word at the end of the sentence, it takes readers just that much longer to reach the signal that shows them the connection.

• Pronouns—Pronouns do the same thing as repeated key words, only more efficiently. In a previous example, I used the pronoun "it" instead of repeating "Peugeot." Of course, the risk you run with pronouns is that readers won't be able to figure out what the pronoun refers to. Pronouns like "it," "this," "which," "that," "they," "them," and the like are vulnerable to this problem. When this happens, the summary transition can help strengthen the transition.

• Summary transitions—At key points in writing, particularly at the beginning or end of paragraphs or sections, you'll see a phrase, sometimes accompanied by a pronoun, that summarizes the preceding discussion. In the same sentence, a statement will be made about that summary phrase—typically this phrase will kick off the upcoming discussion, and do so in a way that the reader sees the connection between what came before and what is coming next. While this may sound like a device to use at the beginning or end of a paragraph, you'll actually see it right in the middle of long and complex paragraphs. (It is here that transitions begin to overlap with topic sentences and overviews, or maybe we should say "reviews.")

• Review-preview transitions—The most powerful transitional device you can use is the type that summarizes the topic of the preceding chunk of information into a short phrase, does the same thing for the upcoming chunk of information, finds the appropriate transitional word, and then throws all these elements together into a sentence or two. You'd use this device at those major bridge points in reports, between large chunks of information—for example, between one 7-page section and a 9-page section that follows it.

• Parallel phrasing—Another transitional device—more of a gimmick actually—is to use the same phrasing in a series of sentences, each one of which adds another detail to some topic. In other words, parallel phrasing is limited to situations where additive logic is involved.

One last way to review your rough draft at the structure level is to check how you have defined the paragraph breaks. Paragraphs are odd creatures—some scholars of writing believe they don't exist and are just arbitrary break points that writers toss in whenever and wherever they damn well please. Sorry—in technical writing, the paragraph is a key player in the battle for clarity and comprehension. Although not always possible, paragraphs should occur where there is some shift in topic or subtopic or some shift in the way a topic is being discussed.

On a doublespaced full page of writing, look for at least one to two paragraph breaks—there's nothing magical about that average so don't treat it as if it were law. Just take a second look at those long paragraphs, and check for the possibility of paragraph breaks. And, while you're reviewing the paragraphing of your rough draft, take another look at the contents of those paragraphs: are there things that don't belong?

Interested in courses related to this page or a printed version? See the resources page.

Return to the main menu of this online textbook for technical writing.