When you look at all the many ways you can review (look for potential problems) and then revise (fix those problems), you might think they’re tedious and time-consuming. Revisions do take time, but the results are worth it. If you analyze writing in the ways outlined in this chapter, the way you write and the way you review what you write will change.

This section covers three major areas to focus on when reviewing your work: structure-level revisions, mid-level revisions and editing, and sentence-level editing.

The subsection on structure-level problems includes tips for checking these aspects of your documents:

• Informational value
• Internal organization
• Topic sentences and overviews

The subsection on mid-level problems focuses on areas where structure- and sentence-level problems overlap:

• Completion and balance
• Paragraph length
• Tone
• Definitions of key terms and concepts

The subsection on sentence-level problems includes tips for how to edit for the following common issues:

• Nominalizations
• Noun stacks
• Redundant phrasing
• Expletives
• Weak use of passive voice verbs
• Subject-verb mismatches
• Readability, sentence lengths, and sentence structures
• Commonly confused words

Structure-Level Revisions

Paying attention specifically to “big picture” items such as informational value, internal organization, and topic sentences will help ensure that your document clearly conveys your ideas and their relationships to each other. If you revise your document with these things in mind, you’ll be able to more accurately meet your audience’s expectations.

Informational Value

One of the most important ways you can review a rough draft is to check its contents for informational value. No matter how well organized it is or how many good transitions and active sentence structures are included, if your technical document doesn’t contain the appropriate information for its audience, it cannot fulfill its purpose. When reviewing a document for informational value, examine your document for the following issues:

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 is insufficient. Take the same example, and imagine that the writer only made a few vague statements about virtual communities. Readers (unless they are experts on virtual communities) likely need at least a paragraph on the subject, if not a comprehensive 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 focused on 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 specifically what you need to do in order to revise.

Internal Organization

If you have the necessary and audience-appropriate information in a technical document, you’re on the right track to crafting a successful document. However, that information may still not be sufficiently organized. When writing and revising a document, consider these two aspects of internal organization—levels (or priority) of information and sequence (or order) of information—on both individual-paragraph and whole-document levels. 

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 type forms a framework that supports the second, subordinate elements of the second type. When thinking about levels of information, envision how a paragraph’s or document’s organization would look in outline format. The broader claims and statements that shape the document would be in Level 1 and Level 2 headings, whereas the detailed evidence, reasoning, and support would appear in lower levels.

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. Reverse outlining, or the practice of creating an outline based off of an already-written document, can also help you visualize the current structure and decide if it needs to change.

Sequence of Information

In addition to grouping information according to its levels, organization refers to the order information appears. This order or sequence is crucial to creating documents that make sense and achieve their purpose. As with a document’s content, you will want to 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 (some of these may be familiar to you from the organizational pattern tables in Chapter 6: Organization and Chapter 14: Oral Communication):

General → specific. Arrange information from general to specific. For example, listing categories of evidence is more general than defining examples of evidence specifically. This pattern is illustrated in Table 10.2.

Table 10.2. Revision with the general-to-specific organizational pattern.

Simple → complex. Begin with the simple and fundamental concepts, and then move on to the more complex and technical.

Thing-at-rest → thing-in-motion. Describe the thing “at rest” (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 and then the data that supports it.)

Problem/question → solution/answer. Introduce a problem or raise a question and 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 providing the technical details. (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 your audience’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.)

The options above are some of many possibilities. Whichever sequence you choose, be consistent 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 will confuse your reader.

Topic Sentences

A topic sentence is a sentence occurring at the beginning of a paragraph that informs the reader of the focus, purpose, and contents of that paragraph (and perhaps one or more paragraphs following). When used well, topic sentences focus the reader’s attention and clarify the organizational structure of a document.

Often, when authors create technical documents, they don’t consciously think about each paragraph’s contents and logic. Instead, many 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, where they’ve just been, and how what they are reading connects to the document as a whole.

Types of Topic Sentences

Different topic sentences achieve different purposes. Therefore, when drafting and revising, consider what you want each paragraph to accomplish for a reader. Use that information along with the examples below to determine which structure is ideal for a particular paragraph or section.

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 or claim—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 mention. This type of topic sentence simply names or reminds the readers about the general subject at hand. It does not forecast what will be said about the subject. Use one to refocus a discussion after a digression or to pull back to the more general topic after you have narrowed the discussion to address specific details about one aspect of the topic. This type of topic sentence serves as a transition between paragraphs. It is often then followed by a second topic sentence that falls into one of the categories described above and focuses the content of the rest of the paragraph.

No topic sentence. Sometimes (very rarely in technical and professional writing), 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 traditional topic sentence up front may be inappropriate.

In addition to clear topic sentences, another crucial way to ensure your sequence of information and your pattern of organization are clearly conveyed to your audience is to make sure you have exceptionally clear transitional sentences and phrases (see Chapter 6: Organization).

Mid-Level Revision and Editing

There is no clear border where higher-order structure-level revision ends and lower-order sentence-level editing begins, as both exist on a spectrum. As you work your way from revising to editing, you will find that recurring choices on the sentence level impact the overall content and structure of your document. While distinguishing structure-level revision and sentence-level editing is helpful, it is also helpful to recognize where they overlap in some specific concepts, rather than trying to categorize them solely into one level or another.

Paragraph Length

While there is no specific rule as to how long your paragraphs should be, in technical and professional writing you will more often rely on short, focused paragraphs as opposed to overly long ones. When determining paragraph length, consider the genre of your document, the content you are presenting, and how your reader will be interacting with any information you provide. This flexible approach will help you determine the “right” paragraph lengths for your document.

As you move from the structural level to the sentence level, check for paragraph breaks. A paragraph break is where one paragraph ends and a new one begins. Insert paragraph breaks where there is a shift in topic or subtopic, or a 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.
• If your technical document does not require long blocks of text, consider breaking it up into very 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.

When you are faced with particularly long blocks of text, think about breaking them up into smaller, distinct portions. This practice is sometimes referred to as chunking your information. Each “chunk” should include a specific and clear topic sentence, followed by 2–3 sentences that elaborate on that topic with more details and specificity. The next paragraph could take the idea into a next level of specificity, either by elaborating on one of the ideas or concepts presented in the latter part of the previous paragraph or introducing a consecutive idea at approximately the same level of specificity.

Transitions

As you transition from one paragraph to the next, you should clearly convey the relationships between the ideas in each paragraph. Just as topic sentences immediately clarify a paragraph’s subject for the reader, transitions help the reader understand how the arrangement of content reflects and/or amplifies the writer’s purpose.  For the writer, transitions can also serve as a litmus test regarding the intuitiveness and fluidity of inter-paragraph transitions.  In other words, the more difficult it is to articulate the relationship between two paragraphs’ content, the more likely the paragraph sequence needs to be rearranged.  Ultimately, smooth transitions help writers frame content in terms of their purpose and facilitate readers’ comprehension (and even appreciation) of content.

Take Control of Your Tone

Does your writing or speech sound pleasant and agreeable, or simple and sophisticated? Conversely, does it come across as stuffy, formal, bloated, ironic, sarcastic, flowery, rude, or inconsiderate? Recognizing our own tone is not always easy, as we tend to read or listen from our own viewpoint and make allowances accordingly.

Once you have characterized your tone, you need to decide whether and how it can be improved. Figuring out how to make your voice match your intentions takes time and skill. One useful tip is to read your document out loud before you deliver it, just as you would practice a speech before you present it to an audience. Sometimes hearing your own words can reveal their tone, helping you decide whether it is correct or appropriate for the situation.

Another way you may learn to assess your own tone is to listen to or watch others’ presentations. Martin Luther King Jr. had one style, while former President Barack Obama has another. The writing in The Atlantic is more sophisticated than the simpler writing in USA Today, yet both are very successful with their respective audiences. What kind of tone is best for your intended audience?

Finally, seek out and be receptive to feedback from teachers, classmates, and coworkers. Don’t necessarily take the word of just one critic, but if several critics point to a speech as an example of pompous eloquence, and you don’t want to come across in your presentation as pompous, you may learn from that example what to avoid.

Define Your Terms

Even when you are careful to craft your message clearly and concisely, not everyone will understand every word you say or write. As an effective communicator, it is your responsibility to give your audience every advantage in understanding your meaning. However, your document or presentation would fall flat if you tried to define each and every term—you would end up sounding like a dictionary.

The solution is to be aware of any words you are using that may be unfamiliar to your audience. When you identify an unfamiliar word, your first decision is whether to use it or to substitute a more common, easily understood word. If you choose to use the unfamiliar word, then you need to decide how to convey its meaning to those in your audience who are not familiar with it. You may do this in a variety of ways. The most obvious, of course, is to state the meaning directly or to rephrase the term in different words, but you may also convey the meaning in the process of making and supporting your points. Another way is to give examples to illustrate each concept or use parallels from everyday life.

Overall, keep your audience in mind and imagine yourself in their place. This will help you to adjust your writing level and style to their needs, maximizing the likelihood that your message will be understood.

Be Results Oriented

Ultimately, the assignment has to be complete. It can be a challenge to balance the need for attention to detail with the need to arrive at the end product—and its due date. Stephen Covey suggests beginning with the end in mind as one strategy for success.^[1] If you have done your preparation, know your assignment goal and desired results, have learned about your audience, and have tailored the message to the audience’s expectations, then you are well on your way to completing the task. No document or presentation is perfect, but the goal of perfection is worthy of your continued effort for improvement.

Therefore, it is crucial to know when further revision will not benefit the presentation or document. Work on knowing when to shift the focus to market testing, asking for feedback, or sharing a draft with a mentor or coworker for a quick review. Determining the balance between completion and revision while engaging in an activity that requires a high level of attention to detail can be a challenge for any communicator, but the key is to keep the end in mind.

Sentence-Level Editing

You’ve probably heard plenty of times that writing should be clear, direct, succinct, and active. This statement is one of those self-evident truths—why would anyone set out to write any other way? However, what does this advice really entail when we apply it? What do sentences that are not “clear” or “direct” look like? What sorts of things are wrong with them? How do you fix them?

Sentences can become redundant, wordy, unclear, indirect, passive, and just plain hard to understand while still remaining grammatically “correct.” All their subjects and verbs agree, the commas are in the right places, and the words are spelled correctly. Still, these sentences are far more difficult to read than a sentence with a comma problem.

The following sections cover seven of the most common sentence-level problems and show you ways of fixing them. Knowing these seven things to watch for will enable you to spot others.

Repetitive Sentence Structures

As you read through your document, you may notice that your sentences, structurally speaking, look very similar. Perhaps you start three sentences in a row with the same word, or you are particularly fond of appositive phrases, or maybe your sentences are almost always over two lines long. While having a distinct style is not a bad thing, redundant phrasing can lead to reader fatigue or disinterest. You can address this issue by varying sentence structures. The basic sentence structure in English begins with the subject, or the primary actor of the sentence. Therefore, one way to insert sentence variety is to start sentences with something other than the subject, such as a verb, a phrase modifying the subject, or a prepositional phrase.

Another way to vary sentence structure is by using coordination by creating compound sentences. Compound sentences are made by joining two independent clauses with a comma and a coordinating conjunction such as “and.” If the two sentences are closely related, you may be able to omit the conjunction and join them with a semicolon instead.

A final way to increase sentence length is by using subordination. Where coordinating means to combine things on an equal level, subordinating means to put one item lower (or subordinate it) to another. When subordinating, use a subordinating conjunction such as “although,” “because,” “even though,” or “while.” Remember, a phrase that starts with one of these conjunctions becomes a dependent clause. This means that the clause can no longer function as a sentence on its own. It needs another independent clause to transform it into a complete sentence. If you begin a sentence with a subordinate conjunction, make sure you conclude its phrase with a comma.

Nominalizations

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,” with the suffix “-tion” appended. Another popular example is a gerund, or verbal noun. In English, these are made by adding “ing” to a verb and using it as a noun. Check your writing for sentences that use a nominalization as the sentence’s subject and use “to be” as the main verb. The “to be” verbs are “am,” “is,” “are,” “was,” and “were.”

Sentences using nominalizations are frequently weak and indirect. Revise them by changing the nominalization into a verb and replacing the “to be” verb. Your sentences will become 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, “information” is a nominalization, but try converting “information” into a main verb. The sentence will be awkward, at best. Sometimes nominalization allows a list to retain parallelism. More often, though, you can convert a nominalization into a main verb.

The following examples in Table 10.3 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 then used to replace the original “to be” main verb. This revision can occasionally slightly alter a sentence’s meaning, so be careful to make sure your new sentences accurately convey the information.

Table 10.3. Nominalizations to verbs.

Noun Stacks

Noun stacks, as the name implies, occur when several nouns are placed in close proximity to each other. These long strings of nouns are notoriously difficult to understand.

Revise these sentences and “unstack” their long noun strings by separating them and transforming them into multiple verbs, clauses, and phrases.

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

Table 10.4. Unstacking nouns.

Redundant Phrasing

Redundant phrasing refers to unnecessary repetition that occurs in close proximity. While some repetition can be useful, especially across paragraphs and documents, redundancies can clutter your writing. Common redundant phrases can come from these three main sources:

Wordy phrases. Look for four- to five-word phrases; you can usually chop them into 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.

Compound synonyms. Look for two or more compounded synonyms. These are two or more words that are indistinguishable in meaning and are placed close together. 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.

Table 10.5 presents some classic examples of wordy phrases and their revised versions.

Table 10.5. Revising wordy phrases.

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.

Table 10.6 presents some examples of sentences with expletives and their revised versions without expletives.

Table 10.6. Removing 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. In simplified terms, the passive voice refers to a sentence construction where the direct object (rather than the actor) is the subject of the sentence. When you use this construction, you will need to use a prepositional phrase (and hence more words) to provide the main verb’s actor, if you choose to provide one at all. While this construction has its advantages, it can easily lead to ambiguity and wordiness.

To locate a sentence using the passive voice, 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. To review how to convert a sentence from active voice to passive voice, and back again, see Table 10.7.

Table 10.7. Passive to active voice.

Sometimes a sentence in the passive voice conveys all the necessary information, as above in Table 10.7. However, the passive voice allows for the actor to be concealed, as Table 10.8 shows.

Table 10.8. Passive-voice concealment.

The ability to conceal the actor or agent of the sentence makes the passive voice a favorite of people in authority—politicians, police officers, city officials, and teachers. Table 10.9 shows how the passive voice can cause wordiness, indirectness, and comprehension problems.

Table 10.9. Passive voice comprehension examples.

Note: All the above examples, regardless of voice, are grammatically correct sentences. Depending on the context, you may prefer to use the passive voice. Instructions and lab reports, as in the final two examples, are places where you may wish to obscure the actor in order to focus on the method.

While there are some risks to using passive construction, the passive voice is nevertheless a great option in certain circumstances. These circumstances include when

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

Subject/Verb Mismatches

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

When editing, make sure every sentence’s subject matches the main verb. Checking for a match can be difficult if the subject and main verb are far apart in the sentence. When this happens, pretend that the words between the subject and verb are gone. Does the verb still make sense with the subject? If so, your subject and verb match.

Table 10.10 provides some examples and their revisions.

Table 10.10. Subject-verb mismatch examples.

Commonly Confused Words

As with most languages, English contains many words that sound similar but that have different spellings and distinct meanings. Table 10.11 below identifies many commonly confused words and their correct usage.

Table 10.11. Commonly confused words in English.

Readability, Sentence Lengths, and Sentence Structures

Highly technical subject matter easily lends itself to multiple long sentences with similar structures that can bore or confuse a reader. To address this common technical writing challenge, you will need to devote revision time to readability, or how easily your audience can comprehend your text. Improving readability involves careful attention to how you present your information in paragraphs and individual sentences.

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 U.S. 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 Microsoft Word, click File > Options > Proofing, check the “Show readability statistics” box, and run the spellchecker.

Sentence Lengths

The average sentence in a technical document should contain about 15 words, but you can use significantly longer or shorter sentences if necessary. Any sentence over 35 words most likely needs to be broken up. An occasional short sentence (say, five to ten words) can be effective, but too many of them at once 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. See Chapter 5: Writing Skills for more information about rhythm on the sentence level.

Sentence Structures

In English, there are four basic sentence structures:

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

Technical writing usually relies upon 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 be lulled by the repetition and find it challenging to concentrate on the meaning. Break apart or combine sentences to create variety in their grammatical structure.

Table 10.12 presents some examples of overly long, complex sentences and their revised versions.

Table 10.12. Overly complex sentence examples and their readability scores.

Note: Readability scores and grade levels are those determined by Microsoft Word’s readability statistics.