Chapter 5: Processes and Guidelines in Technical Writing

5.5: Power-Revision Techniques

By: David McMurrey and Jonathan Arnett

Objectives


Upon completion of this chapter, readers will be able to:

  1. Revise common structure-level problems in technical writing.
  2. Revise common sentence-level problems in technical writing.

Power-Revision Techniques

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.

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

Structure-Level Problems

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.

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:

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:

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 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:

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:

Here are some more advanced types of transitions:

Paragraph Length

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:

In any case, look at long blocks of text and think about breaking them up into bite-sized chunks.

Sentence-Level Revision

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.

Nominalizations

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.

Problem:

The contribution of Quality Circles is mostly to areas of training and motivating people to produce higher quality work.

Revision:

Quality Circles contribute to the training and the motivating of people to produce high quality work.


Problem:

Measurement of temperature is done in degrees of Fahrenheit or Celsius, and its indications are by colored marks on the outside of the thermometer.

Revision:

Temperature is measured in degrees of Fahrenheit or Celsius and is indicated by colored marks on the outside of the thermometer.


Problem:

The beginning of the clonic phase is when the sustained tonic spasm of the muscles gives way to sharp, short, interrupted jerks.

Revision:

The clonic phase begins when the sustained tonic spasm of the muscle gives way to sharp, short, interrupted jerks.


Problem:

During speech, the generation of sound is by vocal chords and the rushing of air from the lungs.

Revision:

During speech, sound is generated by the vocal cords and rushing air from the lungs.


Problem:

The response of the normal ear to sounds is in the audio-frequency between about 20-20,000 Hz.

Revision:

The normal ear responds to sounds within the audio-frequency range of about 20-20,000 Hz.

Noun Stacks

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:

Problem:

There is a growing awareness of organizational employee creative capacity.

Revision:

Awareness of the creative capacity of employees in all organizations is growing.


Problem:

Position acquisition requirements are any combination of high school graduation and years of increasingly responsible secretarial experience.

Revision:

To qualify for the position, you'll need to be a high school graduate and have had increasingly responsible secretarial experience.


Problem:

The Quality Circle participation roles and tasks and time/cost requirements of Quality Circle organizational implementation will be described.

Revision:

The tasks of the participants in Quality Circles and the time and cost requirements involved in the implementation of Quality Circles will be discussed.


Problem:

Proper integrated circuit packaging type identification and applications are crucial to electrical system design and repair.

Revision:

Identifying the proper type of packaging for integrated circuits is crucial to the design and repair of electrical systems.


Problem:

Cerebral-anoxia-associated neonatal period birth injuries can lead to epileptic convulsions.

Revision:

Birth injuries associated with cerebral anoxia in the neonatal period can lead to epileptic convulsions.

Redundant Phrasing

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

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

Expletives

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.

Problem:

When there is a very strong build-up at the front of the plane, it is what is known as a shock wave.

Revision:

When a very strong build-up occurs at the front end of the plane, a shock wave forms.


Problem:

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.

Revision:

When a radioactive substance decays, some form of a high-energy particle—an alpha particle, a beta particle, or a gamma ray—is emitted.


Problem:

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.

Revision:

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

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.

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.

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:

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