Chapter 5: Processes and Guidelines in Technical Writing
5.5: Power-Revision Techniques
By: David McMurrey and Jonathan Arnett
Upon completion of this chapter, readers will be able to:
- Revise common structure-level problems in technical writing.
- Revise common sentence-level problems in technical writing.
The linked chapters here cover 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
- paragraph lengths
The section on sentence-level problems includes tips for how to revise
- noun stacks
- redundant phrasing
- weak use of passive voice verbs
- subject-verb mismatches
- readability, sentence lengths, and sentence structures
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.
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:
There are various types of solar collectors; however the flat-plate solar collector is currently the most common and will be the focus of discussion here. The most important part of a solar heating system is the solar collector whose function is to heat circulating water necessary for space heating. A typical solar collector has layers of glass with intervening air spaces to produce a heat-trapping effect. Most solar collectors consist of a black absorber plate covered by one or more of these transparent cover plates made either of glass or plastic with the sides and the bottom of the collector insulated.
The most important part of a solar heating system is the solar collector whose function is to heat circulating water necessary for space heating. There are various types of solar collectors; however, the flat-plate solar collector is currently the most common and will be the focus of discussion here. A typical flat-plate solar collector has layers of glass with intervening air spaces to produce a heat-trapping effect. Most solar collectors consist of a black absorber plate covered by one or more of these transparent cover plates made either of glass or plastic with the sides and the bottom of the collector insulated.
- 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 most 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.
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 mean while 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).
During Samhain there are a number of activities the Celts took part in that resemble some customs we observe on Halloween today.
- 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.
Most brains exhibit a visible distinction between gray matter and white matter.
- thesis-statement topic sentence. This type of topic sentence makes an assertion—an argument—that the rest of paragraph must support. Use one if your section proves a point and includes multiple supporting statements.
Although Babbage's machines were mechanical monsters, their basic architecture was astonishingly similar to a modern computer.
- 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.
Stress is a measure of the internal reaction between elementary particles of a material in resisting separation, compacting, or sliding that tend to be induced by external forces.
- 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.
The surface of Mars is thought to be primarily composed of basalt, based upon the Martian meteorite collection and orbital observations.
- 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 are part of a popular-science or -technology writing project, a topic sentence up front may be heavy, stodgy, and inappropriate.
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 green summarize the concepts, and dark red words perform the other functions.
The simplest semiconductor is called a diode. A diode serves as a rectifier to conduct alternating current (ac) to direct current (dc). While the usual current in the U.S. is ac with a frequency of 60 Hz, many electronic devices require dc for at least part of their function. The diode solves this mismatch of current types by its basic design in which a p- and an n-type semiconductor are joined together.
- 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 dark red summarize the following materials. The word in purple is the transitional word.
Coring and core analysis techniques are adequate only to a certain extent, as the previous section shows. However, a much faster and less expensive method of detecting fractures is increasingly being used in exploratory wells: wire-line logging analysis.
One last way to revise your rough draft at the structural level is to check for 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 please. This idea may be true for creative or expressive writing, but in technical writing, the paragraph is a key player in the battle for clarity and comprehension. Insert paragraph breaks where there is some shift in topic or subtopic, or some shift in the way a topic is being discussed.
Here are some suggestions for paragraph length:
- If your technical document needs a great deal of expository writing and will be printed in hard copy, you can probably use relatively long paragraphs. A single spaced page full of text will probably contain one to four paragraph breaks. (There's nothing magical about that average, so don't treat it as if it were law.)
- If your technical document does not require long blocks of text, consider breaking it up into short paragraphs. Three sentences per paragraph is a widely accepted average.
- If your technical document will be posted online, use short paragraphs. People generally find it easier to read short paragraphs online than to read long paragraphs online.
In any case, look at long blocks of text and think about breaking them up into bite-sized chunks.
You've probably heard plenty of times that writing should be lean, mean, clear, direct, succinct, active, and so on. This statement is one of those self-evident truths—why would anyone set out to write any other way? But what does this advice really mean? What do sentences that are not "lean, mean" and so on look like? What sorts of things are wrong with them? How do you fix them?
Sentences do have ways of becoming flabby, redundant, wordy, unclear, indirect, passive, and just plain old hard to understand. Even so, they remain grammatically "correct"—all their subjects and verbs agree, the commas are in the right places, the words are spelled correctly. Still, these sentences are far more difficult to read than a sentence with just a comma problem.
The following sections can't pretend to cover all of the ways sentences can go bad at this higher level, but they do cover seven of the most common problems and show you ways of fixing them. And knowing these seven will probably enable you to spot others we have not trapped and labeled yet.
Check your writing for sentences that use "to be" as the main verb and use a nominalization as the sentence's subject. (A nominalization is a verb that has been converted into a noun; look for -tion, -ment, -ance, and other suffixes. For example, "nominalization" is itself a nominalization; the root verb is "to nominate." The "to be" verbs are am, is, are, was, were.)
These sentences are probably weak and indirect. Revise them by changing the nominalization into a verb and replacing the "to be" verb. Your sentences will sound more active, and they will be easier for the reader to understand.
Sometimes, you can't convert a nominalization into a main verb, or a nominalization needs to remain a sentence's subject. (For example, "infomation" is a nominalization, but try converting "information" into a main verb. The sentence will be awkward, at best.) More often, though, you can convert that nominalization into a main verb.
The following examples demonstrate this problem and how to fix it. In each revised version, notice how a noun has been converted into the sentence's main verb and replaced the original "to be" main verb.
The contribution of Quality Circles is mostly to areas of training and motivating people to produce higher quality work.
Quality Circles contribute to the training and the motivating of people to produce high quality work.
Measurement of temperature is done in degrees of Fahrenheit or Celsius, and its indications are by colored marks on the outside of the thermometer.
Temperature is measured in degrees of Fahrenheit or Celsius and is indicated by colored marks on the outside of the thermometer.
The beginning of the clonic phase is when the sustained tonic spasm of the muscles gives way to sharp, short, interrupted jerks.
The clonic phase begins when the sustained tonic spasm of the muscle gives way to sharp, short, interrupted jerks.
During speech, the generation of sound is by vocal chords and the rushing of air from the lungs.
During speech, sound is generated by the vocal cords and rushing air from the lungs.
The response of the normal ear to sounds is in the audio-frequency between about 20-20,000 Hz.
The normal ear responds to sounds within the audio-frequency range of about 20-20,000 Hz.
Search your writing for sentences that contain long, piled-up strings of nouns. Their effect on a reader is similar 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:
There is a growing awareness of organizational employee creative capacity.
Awareness of the creative capacity of employees in all organizations is growing.
Position acquisition requirements are any combination of high school graduation and years of increasingly responsible secretarial experience.
To qualify for the position, you'll need to be a high school graduate and have had increasingly responsible secretarial experience.
The Quality Circle participation roles and tasks and time/cost requirements of Quality Circle organizational implementation will be described.
The tasks of the participants in Quality Circles and the time and cost requirements involved in the implementation of Quality Circles will be discussed.
Proper integrated circuit packaging type identification and applications are crucial to electrical system design and repair.
Identifying the proper type of packaging for integrated circuits is crucial to the design and repair of electrical systems.
Cerebral-anoxia-associated neonatal period birth injuries can lead to epileptic convulsions.
Birth injuries associated with cerebral anoxia in the neonatal period can lead to epileptic convulsions.
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:
Wordy Phrase Revised Phrase in view of the fact that since, because at this point in time now, then it is recommended that we recommend as per your request as you requested in light of the fact that since, because being of the opinion that I believe in the near future soon during the time that when it would be advisable to should, ought due to the fact that since, because in this day and age now, currently for the reason that since, because in my own personal opinion I believe, in my opinion, I think to the fullest extent possible fully in accordance with your request as you requested four in number four predicated upon the fact that based on inasmuch as since, because pursuant to your request as you requested in connection with related to take cognizance of the fact that realize it has come to my attention that I have learned that with reference to the fact that concerning, about with regard to concerning, about in close proximity to near, close, about to the extent that as much as in the neighborhood of near, close, about until such time as until has the ability to can that being the case therefore
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.
When there is a very strong build-up at the front of the plane, it is what is known as a shock wave.
When a very strong build-up occurs at the front end of the plane, a shock wave forms.
When there is decay of a radioactive substance, there is the emission of some form of a high-energy particle—an alpha particle, a beta particle, or a gamma ray.
When a radioactive substance decays, some form of a high-energy particle—an alpha particle, a beta particle, or a gamma ray—is emitted.
It is the results of studies of the central region of the M87 galaxy that have shown that there are stars near the center that move around as though there were some huge mass at the center that was attracting them.
Recent studies of the central region of the M87 galaxy have shown stars near the center moving around as though some huge mass at the center were attracting them.
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.
Passive Voice: The report was written by the student.
Active Voice: The student wrote the report.
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.
Passive Voice: The papers will be graded according to the criteria stated in the syllabus.
Graded by whom, though?
Active Voice: The teacher will grade the papers according to the criteria stated in the syllabus.
Oh! That guy...
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.
Passive Voice: Your figures have been reanalyzed in order to determine the coefficient of error. The results will be announced when the situation is judged appropriate.
Who analyzes, and who will announce?
Active Voice: We have reanalyzed your figures in order to determine the range of error. We will announce the results when the time is right.
Passive Voice: Almost all home mortgage loans nowadays are made for twenty-five years. With the price of housing at such inflated levels, those loans cannot be paid off in any shorter period of time.
Who makes the loans, and who can't pay them off?
Active Voice: Almost all home mortgage loans nowadays are for twenty-five years. With the price of housing at such inflated levels, homeowners cannot pay off those loans in any shorter period of time.
Passive Voice: However, market share is being lost by ride-share operators, as is shown in the graph in Figure 2.
Who or what is losing market share, who or what shows it?
Active Voice: However, ride-share operators are losing market share, as the graph in Figure 2 shows.
Passive Voice: For many years, federal regulations concerning the use of wire-tapping have been ignored. Only recently have tighter restrictions been imposed on the circumstances that warrant it.
Who has ignored the regulations, and who is imposing them?
Active Voice: For many years, government officials have ignored federal regulations concerning the use of wire-tapping. Only recently has the federal government imposed tighter restrictions on the circumstances that warrant it.
Passive Voice: After the arm of the hand-held stapler is pushed down, the blade from the magazine is raised by the top-leaf spring, and the magazine and base.
Who pushes it down, and who or what raises it?
Active Voice: After you push down on the arm of the hand-held stapler, the top-leaf spring raises the blade from the magazine, and the magazine and base move apart.
Passive Voice: The solution was heated to 28.4 degrees Celsius and was stirred for 9 minutes and 1 second.
Who heated the solution, and who or what stirred it?
Active Voice: My lab partner and I heated the solution to 28.4 degrees Celsius and took turns stirring it for 9 minutes and 1 second.
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.
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.
Problem: The causes of the disappearance of early electric automobiles were devastating to the future of energy conservation in the U.S.
Revision: The disappearance of early electric automobiles destroyed the future of energy conservation in the U.S.
Problem: Presently, electric vehicles are experimenting with two types of energy sources.
Revision: Presently, research on electric vehicles involves two types of energy sources.
Problem: Consequently, the body is more coordinated and is less likely to commit mental mistakes.
Revision: Consequently, workers will be more coordinated and commit fewer mental errors.
Readability, Sentence Lengths, and Sentence Structures
When you are writing about 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.
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.)
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.
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:
Problem: In order to understand how a solid, liquid or gas can be made to give off radiation in the form of a laser beam, one must understand some of the basic theory behind laser light.
Length: 35 words
Grade level: 15.2
Revision: A solid, liquid or gas can be made to give off radiation in the form of a laser beam. Understanding this process requires some knowledge about the basic theory behind laser light.
Average length: 16 words
Grade level: 9.0
Problem: Laser beams, which have many properties that distinguish them from ordinary light, result from the emission of energy from atoms in the form of electromagnetic waves whose range in most laser beams is 10-3 to 10-7 meters.
Length: 37 words
Grade level: 19.5
Revision: Laser beams are just beams of light, but they have special properties that distinguish them from ordinary light. Laser beams come from atoms that emit energy as electromagnetic waves. The average wavelength ranges from 10-3 to 10-7 meters.
Average length: 12.6 words
Grade level: 10.7