Chapter Attribution

David McMurry and Jonathon Arnett

Power Revision Techniques

This chapter covers some of the most important aspects of writing—what’s more important than the information you put in a document, how you organize it, how you link it all up together?

When you look at all these powerful ways you can review (look for potential problems) and then revise (fix those problems), you might think they’re tedious and time-consuming. They do take some time, but don’t worry…this stuff becomes second nature rather quickly. If you spend some time analyzing writing in the ways outlined in this chapter, the way you write and the way you review what you write will change. You’ll start operating—even if you don’t consciously realize it—with these ideas in mind.

This chapter covers two major categories of problems you can revise: structure-level problems and sentence-level problems.

The section on structure-level problems includes tips for checking your documents.

• informational value
• internal organization
• topic sentences and overviews
• transitions
• paragraph lengths

The section on sentence-level problems includes tips for how to revise

• nominalizations
• noun stacks
• redundant phrasing
• expletives
• weak use of passive voice verbs
• subject-verb mismatches
• readability, sentence lengths, and sentence structures

Informational Value

One of the most important ways you can review a rough draft is to check its contents for informational value. All the good transitions, good organization, and clear sentence structure in the world can’t help a technical document that doesn’t have the right information for its audience.

• Information is missing. For example, imagine that somebody wrote a technical report on “virtual communities” but never bothered to define what “virtual community” means. The reader would be utterly lost.
• Information is there, but not enough. Take the same example, and imagine that the writer only made a few vague statements about virtual communities. The reader (unless she is an expert on virtual communities) needed at least a paragraph on the subject, if not a full-blown three- or four-page section.
• Information is there, but at the wrong level for the audience. Imagine that the report’s writer included a two-page explanation of virtual communities but included highly technical information and phrased it in language that only a sociologist (an “expert” academic audience) would understand when the document was really intended for high-school students. The writer failed to match the readers’ knowledge, background, and needs.

If you can get a sense of how information does or doesn’t match your audience, 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.

Internal Organization

If you have the necessary and audience-appropriate information in a technical document, you’re on the right track. However, that information may still not be sufficiently organized—like when you’ve just moved and everything is a mess or still in boxes—and you need to consider the rough draft’s internal organization. Always consider these two aspects of internal organization, on both an individual-paragraph and whole-document level:

• the levels of information
• the sequence of information

Levels of Information

Some paragraphs and sentences contain general information or broader statements about the topic being discussed. Others contain more specific information or go into greater depth. The first elements form a “framework” that supports the second, “subordinate” elements.

When you revise, check if the document’s framework is easy to follow. The most common and effective way to arrange general and specific information is to introduce the framework first, then follow it with specifics. This overarching pattern holds for sentences inside paragraphs and paragraphs inside longer documents, even if the paragraph or document uses a different sequence of information.

Sequence of Information

Match a technical document’s internal sequence of information to the document’s audience, context, and purpose. Here are some examples of common informational sequences:

General > specific. 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 here:

• simple > complex. Begin with the simple, basic, fundamental concepts and then move on to the more complex and technical.
• thing-at-rest > thing-in-motion. Describe the thing (as if in a photograph), then discuss its operation or process (as if in a video).
• spatial movement. Describe a pattern of physical movement; for example, top to bottom, left to right, or outside to inside.
• temporal movement. Describe events in relation to what happens first, second, and so on.
• concept > application of the concept / examples. Discuss a concept in general terms, then discuss the concept’s application and/or examples of the concept.
• data > conclusions. Present data (observations, experimental data, survey results) then move on to the conclusions that can be drawn from that data. (This pattern is sometimes reversed: present the conclusion first, then the data that supports it.)
• problem / question > solution / answer. Introduce a problem or raise a question, then move on to the solution or answer.
• simplified version > detailed version. Discuss a simplified version of the thing, establish a solid understanding of it, then explain it all again, but this time laying on the technical detail. (This approach is especially useful for explaining technical matters to nonspecialists.)
• most important > least important. Begin with the most important, eye-catching, dramatic information, and move on to information that is progressively less so. (This pattern can be reversed: you can build up to a climax, rather than start with it.)
• strongest > weakest. Start with the strongest argument for your position—to get everybody’s attention—then move on to less and less strong ones. (This pattern can also be reversed: you can build up to your strongest arguments, but the weakest → strongest pattern is often less persuasive.)

These are just a few possibilities. Whichever sequence you choose, be consistent with it, and avoid mixing these approaches randomly. For example, presenting some data, stating a few conclusions, and then switching back and forth between data and conclusions haphazardly will only confuse your reader.

Topic Sentences

One of the best structural revision techniques you can use is to backtrack through a rough draft and insert topic sentences at key points.

A topic sentence is a sentence occurring toward the beginning of a paragraph that in some way tips the reader off as to the focus, purpose, and contents of that paragraph (and perhaps one or more paragraphs following). At its best, it focuses the reader’s attention; it says, “Hey, here’s what we’re talking about!”

Often, when authors create technical documents, they don’t consciously think about each paragraph’s contents and logic; instead, authors focus on getting words onto the page, and they figure out what they meanwhile they’re writing. Sometimes the results can seem disjointed. Accordingly, authors should go back and insert topic sentences that can help readers understand where they are going, what’s coming up next, (often) where they’ve just been, and how what they are reading connects to the document as a whole.

Types of Topic Sentences

Your best guide for deciding when to use topic sentences and which type to use is probably your own instincts and intuition. But here are some ideas and examples:

• keyword topic sentence. This type of topic sentence contains a keyword that hints about the content and organization of the upcoming material. Use one if your section (one or more paragraphs) discusses multiple similar things (for example, problems, solutions, causes, consequences, reasons, aspects, factors).

• overview topic sentence. This type of topic sentence names all the subtopics in the upcoming material. Use one if you want to specify all the subtopics you will address.

• thesis-statement topic sentence. This type of topic sentence makes an assertion—an argument—that the rest of the paragraph must support. Use one if your section proves a point and includes multiple supporting statements.

• topic definition. This type of topic sentence names the term being defined, identifies the class it belongs to, and describes its distinguishing characteristics. It must contain highly specific information. Use one if your section introduces an unfamiliar term.

• topic reference. This type of topic sentence simply mentions the general subject at hand. It does not forecast what will be said about the subject. Use one to remind your reader about the general subject.

• no topic sentence. Sometimes, you may not need or want a topic sentence. If your materials contain a story that leads to a point, or is part of a popular-science or -technology writing project, a topic sentence upfront may be heavy, stodgy, and inappropriate.

Transitions

You may have audience-appropriate information in your technical document, and you may have organized that information well, but you also need to integrate those various pieces of information into a unified whole. If you don’t make the document’s “flow” of ideas clear, the document will read like a random assortment of ideas, and the reader will not understand how the chunks of information relate or connect to each other.

Use “transitions”—various devices that help readers connect the different sections of a document—to guide your reader from one idea to the next. You need to make clear the logic that connects every sentence in a document.

Here are some common types of transitional words and phrases:

• additive. Use these words to demonstrate that one idea is added to another. Examples include moreover, as well as, too, in addition to, furthermore, also, additionally.
• narrative / chronological / temporal. Use these words to demonstrate that one idea can follow, precede, or occur simultaneously with another. Examples include then, next, after, before, since, subsequently, following, later, as soon as, as, when, while, during, until, once.
• contrastive / comparative.Use these words to demonstrate differences or similarities. Examples include but, on the other hand, unlike, as opposed to, than, although, though, instead, similarly.
• alternative.Use these words to demonstrate that two ideas can act as alternatives or substitutes for each other. Examples include either, or, nor, on the other hand, however, neither, otherwise.
• causal. Use these words to demonstrate that one idea can be the cause or the result (effect, consequence, etc.) of another. Examples include thus, then, unless, subsequently, therefore, because, consequently, as a result, if, in order to/that, for, so.
• illustrative. Use these words to demonstrate that one idea can be an example or an illustration of another. Examples include for example, for instance, to illustrate, as an example.
• repetitive / reiterative. Use these words to rephrase an idea using other, perhaps more familiar, terms. Examples include in other words, in short, that is, stated simply, to put it another way.
• spatial/physical. Use these words to emphasize spatial relationships between things. Examples include prepositions such as under, beside, on top of, next to, behind, and many others.

Here are some more advanced types of transitions:

• summary transitions. Use a brief phrase (sometimes even a single word) to summarize the concepts in the preceding material. Then, in the same sentence, make a statement about that summary phrase, introduce the upcoming materials, and demonstrate their conceptual link. This technique is especially useful for establishing logical links between short sections. In the following sample paragraph, the words in black summarize the concepts, and the underlined words perform the other functions.

• review-preview transitions. Use a relatively short phrase or sentence to summarize the topic of the preceding material, use another relatively short phrase or sentence to summarize the upcoming material, and tie them together using transitional words. In the following sample paragraph, the words in green summarize the previous ideas. The words in black summarize the following materials. The word in the quotation marks is the transitional word.

Noun Stacks

Search your writing for sentences that contain long, piled-up strings of nouns. Their effect on a reader is similar to being hit in the head with a large, blunt object.

Revise these sentences and “unpack” or “unstack” their long noun strings into multiple verbs, clauses, and phrases.

The following examples demonstrate this problem and how to fix it. In each revised version, notice how a long string of nouns has been broken apart:

Redundant Phrasing

Eliminate redundant phrases in your writing. They can come from these three sources (but there are probably plenty more):

• wordy set phrases: Look for four- to five-word phrases; you can usually chop them to a one- to two-word phrase without losing meaning. For example, “in view of the fact that” can be reduced to “since” or “because.”
• obvious qualifiers. Look for a word that is implicit in the word it modifies. For example, phrases like “anticipate in advance,” “completely finish,” or “important essentials” are examples of obvious qualifiers.
• scattershot phrasing. Look for two or more compounded synonyms. For example, “thoughts and ideas” (what’s the difference?) or “actions and behavior” (if there is a difference between these two, does the writer mean to use it?) are common.

Here are some classic examples of wordy set phrases and their revised versions:

Expletive

In grammar, an “expletive” is a word that serves a function but has no meaning. The most common expletive phrases in English are “it is/are” and “there is/are.” They are sometimes useful, but they are more often redundant and weaken a sentence’s impact. If you can, delete them from technical documents.

Here are some examples of sentences with expletives and their revised versions without expletives

Weak Use of Passive-Voice Verbs

One of the all-time worst offenders for creating unclear, wordy, indirect writing is the passive-voice construction.

Look for a “to be” verb coupled with a past participle (a past-tense verb, often ending in -ed). Change it to an active verb, and rearrange the sentence to make grammatical sense.

It’s easy enough to convert a sentence from active voice to passive voice, and back again.

However, the passive voice can be a shifty operator—it can cover up its source, that is, who’s doing the acting, as this example shows.

It’s this ability to conceal the actor or agent of the sentence that makes the passive voice a favorite of people in authority—policemen, city officials, and, yes, teachers. At any rate, you can see how the passive voice can cause wordiness, indirectness, and comprehension problems.

Don’t get the idea that the passive voice is always wrong. It is a good writing technique if

• the subject is obvious or too-often-repeated
• the actor is unknown
• the actor isn’t important
• we want to stress the action more than who did it
• we need to rearrange words in a sentence for emphasis.

Notice that the passive voice is really all right in the last two examples above.

Subject-Verb Mismatches

In dense, highly technical writing, it’s easy to lose track of the real subject and pick a verb that just does not make sense. The result is a noun physically not able to do what the verb says it is doing, or some abstract thing performing something nitty-gritty real-world action.

Check to make sure every sentence’s noun matches the main verb.

Here are some examples and their revisions.

Examples

Readability, Sentence Lengths, and Sentence Structures

When you are writing about the highly technical subject matter, it is easy to construct long sentences that become hard to read, or to bore your reader with highly repetitive sentence lengths and grammatical structures.

Readability

The reader of a technical document needs to be able to extract information from it as easily as possible, so most technical documents are written at the 8th-grade level. The average sentence length should be about fifteen words.

When you revise, look for long sentences that contain lots of information. Break them into shorter, bite-sized chunks that contain single ideas, and run the resulting sentences through a readability checker. For example, MS Word has a built-in readability tool that will tell you the number of words per sentence and the Flesch-Kincaid model’s estimate of the text’s grade level. (Open your document in MS Word, click File > Options > Proofing, check the “Show readability statistics” box, and run the spellchecker.)

Sentence Length

The average sentence in a technical document should contain about fifteen words, but you can use significantly longer or shorter sentences if necessary. Any sentence over thirty-five or forty words almost definitely needs to be broken up. An occasional short sentence (say, five to ten words) can be very effective, but lots of them can cause writing to be choppy and hard to follow.

Similarly, if the document contains a string of sentences that are close to the same length (for example, six sentences of exactly fifteen words each), the reader will fall into a rhythm and find it hard to pay attention. Break apart or combine sentences to create variety in their length.

Sentence Structures

In English, there are four basic sentence structures:

• simple. This type of sentence contains a single independent clause.
• compound. This type of sentence contains two independent clauses.
• complex. This type of sentence contains an independent clause and a dependent clause.
• compound-complex. This type of sentence contains a compound sentence and at least one dependent clause.

Technical writing usually uses simple and compound sentences, and sometimes complex sentences. It very rarely uses compound-complex sentences. Look for these sentence structures and revise your technical document accordingly.

Also, as with sentence lengths, if all your sentences use the same grammatical structure, your reader will fall into a rhythm and find it hard to pay attention. Break apart or combine sentences to create variety in their grammatical structure.

Here are some examples of overly long, complex sentences and their revised versions:

Examples