People most often read technical manuals to find answers to problems that they are having with software or hardware. They need their questions answered concisely and accurately. Concise writing means readers do not have to contend with unnecessary technical jargon. Write simple and direct sentences. Use short, familiar words, but respect the reader’s level of technical knowledge and competency. Simple, direct, and accurate writing makes a document more usable and easier to translate.

Readers project some significance onto every change in tone, language, or typographic convention. A consistent style enables readers to internalize the language and text conventions of a document. As a result, understanding occurs more easily and significant points stand out more clearly. Consistency is one of the most valuable aspects of good style.

Writers frequently incorporate jargon associated with the subject matter into their documentation. Jargon can be difficult for the “uninitiated” to understand. In addition, jargon can be very difficult to translate.

In the following example, a writer uses the specialized phrases of the computer industry in a hardware manual:

The writer introduces the phrase “powering down,” while admitting that the phrase only means turning off the power. The writer further confuses the reader by introducing “shut down” immediately after the term “powering down.”

Rewrite: Using common English shortens the preceding example and permits the writer to be more specific and helpful.

When you have to use computer terms, introduce them in italic, explain them, include them in a glossary, and use them consistently.

Always try to write in the active voice, but do not fear the correct, thoughtful use of the passive voice. Writing entirely in the active voice is nearly impossible to achieve, so know when to use the passive voice.

Because writers in the computer industry often insist on using the active voice, the writer of the following example introduces a message with this sentence:

Rewrite: A message does not display. Rather, a message appears or is displayed by the system. The passive voice can indicate that the subject is the receiver of the action rather than the performer.

Make your writing active by concentrating on the activity of your subject. Use the passive voice when it is unavoidable because the performer of the action is either unimportant to the reader or unidentifiable.

Readers use technical documents to perform tasks or gather information. For readers, these activities take place in the present. Therefore, the present tense is appropriate in most cases. Only use the future tense when necessary.

Convoluted sentences or sentences densely packed with information cause confusion, slow the reading process, and are difficult to translate. Any sentence that attempts to convey too much information is too long, regardless of its word count. Use punctuation, rhythm, and clarity of meaning to regulate sentence length and to attain a style that is easy to understand.

Write as if you were talking to a person, rather than formulating a law or theorem. Consider the following example:

Comments: A person would never speak that sentence. The sentence is grammatically correct, but it is stiff and formal. Ask yourself, “Does this sound like me responding to a question?”

To get a response such as the previous example, a person would have had to ask, “How can I scroll directly to the relative location of text in my document?” More likely the person would ask, “If what I want to read is way up or way down in the document, how can I get to it without scrolling through every line?”

Rewrite: Respond naturally to the reader’s question. Remember that the reader is a person who wants to do something.

Make sure that you distinguish between restrictive and nonrestrictive clauses. Consider the differences in meaning for the following two sentences:

In the first sentence, the reader is told to check the LED specifically on the front panel, not the one on the side panel or back panel.

In the first part of the second sentence, the reader is told merely to check the LED. The second part of the sentence also states that the LED happens to be on the front panel. This clause implies that no other LED exists anywhere else. The minor difference in meaning could confuse translators or nonnative speakers of English.

Make sure that you include the word “that” when introducing a restrictive clause.

Divide nonrestrictive clauses that are associated with a relative pronoun into separate sentences. This separation can help the translator to understand the meaning.

Always write concisely. Avoid paragraphs that are so dense with information that the reader must struggle to understand the information. For instance, the reader struggles to make sense of the following paragraph:

Comments: The paragraph attempts to deliver too much information. Almost every sentence in the example conceals a smaller bit of information, which in turn conceals an even smaller bit of information, and so on.

Even the reader who understands all of the technical language faces the chore of sorting and retrieving all the information. Count the facts and concepts presented in each sentence. Do not count repeats.

The reader’s burden is to receive, translate, comprehend, or otherwise deal with one technical fact or technical concept every seven words.

The issue is clarity, not space.

Look at each paragraph that you write. If the paragraph looks too long, it is too long. Present general information at the beginning of the paragraph. Add details in descending order of importance toward the end. Use as much space and as many paragraphs as you need to make sense.

Rewrite: Divide some sentences into two sentences. Divide the example into several paragraphs.

Often a product provides several different ways to accomplish a single task. You might decide that you owe the reader an explanation of each method. However, remember that the reader is more interested in using the product than in understanding all options. Choose the best method for most of your audience, and tell the reader to use that method.

After you commit to the best course of action, you might explain to the reader that other methods exist. Tell the reader where to find your descriptions of those methods. Also, tell the reader why and in what situations options A, B, and C are useful.

For example, the writer of a user’s guide for a DOS application included all of the possibilities in this text:

Comments: The writer reveals consequences but no guidelines. The details seem to be there, but the entire passage is ambivalent. The writer does not tell the reader why the choice exists. The reader is left to decide without guidance.

Watch for words that could lead to unguided choices. Avoid ambivalent words and phrases, such as the following:

When you write these words or phrases, or similar ones, make sure that you are prepared to explain the benefits of the choices.

Rewrite: The writer recognized that the passage was ambivalent because the passage did not guide the reader. The rewritten passage guides the reader with this explanation.

One of the most important contributions a writer makes is to anticipate the reader’s questions and provide appropriate answers. A writer must anticipate questions about related topics as well and provide cross-references to where those questions are answered. As the subject matter expert, a writer can create a climate of understanding that is far more significant than merely recounting facts about the product.

For example, when you review a procedure in your document with the reader’s perspective in mind, ask these questions:

A great temptation for writers of computer documentation is to inject a note of levity into the text. Resist this temptation. Even genuinely humorous commentary is a distraction and becomes annoying on subsequent readings. Likewise, humor that descends into user-friendly chumminess never works. A sympathetic reader might forgive you for trying to “lighten up” the text, but another reader might resent a chummy tone.

For example, this humor was injected into a tutorial:

Comments: The phrase “one without fur” detracts from the content of the sentence and distracts the reader. The goal of the sentence was to tell the reader that the mouse is related to the window system. The apparent goal of the humor was to reassure the reader that the mouse is “friendly.”

Rewrite: The following revision pursues those goals in a direct, conversational tone:

Humor is difficult, if not impossible, to translate successfully. Humor is usually cultural. What might be funny to an American could be offensive to readers in another country.

Regarding the issue of sexism in language, appearances count.

In many cultures, language has developed so that “men” often refers to “men and women,” and “he,” “him,” and “his” are regarded as gender-neutral words. In decades past, this sentence might have been perfectly acceptable:

Today, this usage of “he” and “his” is far less acceptable. These pronouns assume too much about the gender of an individual. Writers who defend the use of such pronouns must contemplate the following: Many readers could interpret a writer’s intentions negatively and could consciously or subconsciously reject the work.

A “naive reader” is not unsophisticated. Treat the reader as a peer.

Unintentionally, this sentence is condescending:

Comments: The sentence belittles the reader’s anxiety. In an effort to reassure the naive user, the writer seems to belittle the reader’s genuine fear of doing something wrong. Of course, the computer will not “bite” the user, and of course the reader can see the writer’s point. But the writer makes this point as though writing for a juvenile. A reader might find the tone condescending and insulting.

Remember that the reader might be naive only in relation to the particular computer technology you are documenting. Credit even the least experienced computer user with intelligence and life experience. Show respect for this person when you write.

Rewrite: Get directly to the point, and be positive rather than negative.

Anthropomorphisms attribute human motivation, characteristics, or behavior to inanimate objects. Anthropomorphisms often creep into technical writing. Avoid using anthropomorphisms. Follow these guidelines:

Command names are only names. Command names are never verbs.

You create redundancies when you fail to consider the literal meanings of the words that you choose. Some common examples of redundancies and alternatives are listed in the following table.

Test the usefulness of each modifier you choose. If the modifier does not help the construction, for example, if it does not amplify, clarify, or intensify the meaning of the word that it modifies, do not use it. If the modifier’s meaning is equal to the meaning of the word that it modifies or if the phrase or clause is a virtual restatement of a point previously made in the sentence, do not use it.

Well-used “intensives,” however, often add emphasis to the sentence. For example, “turn on your system for the very first time” might appear redundant at first glance. Something cannot be any more “first” than first. But the intensive, “very,” makes clear that the ensuing description happens only once in the system’s life. Use this technique sparingly.

One way to learn good style is to analyze examples of effective technical writing. Appendix D lists books worthy of your professional attention. Study the literature in your area of specialization and ask yourself what works, what doesn’t, and why.

As you analyze examples of effective technical writing, you will see that writers of effective technical prose present material as follows:

If you are fortunate enough to work at a site with an editorial staff, take every opportunity to have your work edited. A good editor is an invaluable partner in producing effective documentation. An editor can often assist you in determining the best way to present information to the customer and to international readers. Your editor is also the expert in your company style.

A good editor is often familiar not only with other documentation produced at your company but also with other documentation in your field. An editor relates to a document as an advocate for the reader and as a professional who can critique your work. An editor is often the first “customer” to read your document.

For further discussion of the partnership between writers and editors, see Chapter 10.

Technical writing is a recognized profession. An excellent way to improve your style is to attend classes offered by other professionals in the field. Classes are also often available through the following avenues: