A Usage and Style Guide

For Technical Communicators

Technical communicators have traditionally aimed to produce clear-cut, readable prose. The following are a handful of approaches that you can use to help your documents to accomplish their rhetorical work more effectively. Keep in mind, however, that these are not hard and fast rules. Rather, these recommendations are designed to turn your attention to some very important textual details that play a role in how your documents work persuasively.

1. Say things as simply as you conceivably can. Your writing may contain phrases that are more complicated than they need to be—don't be affraid to edit away this kind of complexity for fear of sounding simplistic. Simple prose is not the same as stupid prose.

Original

Revision

We don't have toner at this moment in time.

We don't have toner now.

We need the toner in order to print the manuals.

We need the toner to print the manuals.

The invoice was lost due to the fact that the TPS report didn't have it's cover sheet.

The invoice was lost because the TPS report didn't have it's cover sheet.

I was aware of the fact that cover sheets are needed for TPS reports.

I know that TPS reports need cover sheets.

2. Use the active voice. Sentences in the active voice are generally more readable, and you should use it for most kinds of everyday communication. Active sentences mention who did the action (the subject) right up front, while passive sentences mention who did the action later on, or don't mention them at all.

Keep in mind that there are some cases where the passive voice is rhetorically more appropriate or it can't be avoided. At other times, it may be a formal requirement for your documents, as in some report and proposal styles.

Passive Voice

Active Voice

The manual was written by the document team.

The document team wrote the manual.

The pesticides are sprayed by Milton.

Milton sprays the pesticides.

Precipitation effects were observed.

We observed precipitation effects.

Mistakes were made.

I made mistakes.

3. Stay "Verbular." Emphasize action over things. Turning nouns into verbs usually makes sentences easier to comprehend:

"Nounular"

"Verbular"

Our approach provides benefits to consumers.

Our approach benefits consumers.

Make an evaluation of the work environment and provide analysis of the available resources.

Evaluate the work environment and analyze the available resources.

It's time to implement a complete overhaul of the TPS report revision oversight procedure.

We need to overhaul how we oversee TPS report revisions.

Perform an online search for the relevant material.

Google the relevant material.

4. Don't use too many prepositions. Prepositions are words like at, on, of, in, by, and for. Too many of these words in one sentence tends to be confusing:

Lots of Prepositions

Fewer Prepositions

The use of steroids by players in baseball in America is reprehensible.

The use of steroids by American baseball players is reprehensible.

Wesley Willis' "Birdman Kicked my Ass" is the music in the menu on the DVD for the animated series, Harvey Birdman, Attorney at Law.

Wesley Willis' "Birdman Kicked my Ass" is the menu music on the Harvey Birdman, Attorney at Law DVD.

5. Stay parallel. Having good parallelism means that items in a list are grammatically similar. If a list doesn't jump around between nouns, verbs, adjectives, infinitives, etc., it's generally easier to make sense of:

Not Parallel

Parallel

We encourage students to practice good writing, including planning, revision, editing, evaluating sources, and working with others. We encourage students to practice good writing, including planning, revising, editing, evaluating sources, and working with others.

The fax machine is affordable, works efficiently, and you can depend on it.

The fax machine is affordable, efficient, and dependable.

I plan to put the cover on the TPS report this time, as well as reading the TPS memo.

I plan to put the cover on the TPS report this time, and to read the TPS memo.

We are committed to providing outstanding customer service, efficient communication with our team members, and making a profit.

We are committed to providing outstanding customer service, communicating efficiently with our team members, and making a profit.

6. Syntax. Make sure that stuff that belongs together in a sentence doesn't get separated by some other phrase:

Original Syntax

Revised Syntax

Rhetoric, through most of history, referred to the arts of speechmaking and oratory.

Through most of history, rhetoric referred to the arts of speechmaking and oratory.

Born in East Prussia, Alexander's family escaped during World War I to Berlin. Born in East Prussia, Alexander's family escaped to Berlin during World War I.

Dr. Bancroft's research indicates that at least one user of oral contraceptives in four has sexual side effects.

Dr. Bancroft's research indicates that at least one in four users of oral contraceptives has sexual side effects.

The next year, after Mr. Wilson became a vocal critic of the Bush administration's Iraqi intelligence, the identity of his wife, Valerie Wilson, a C.I.A. officer who suggested him for the Niger trip, was made public.

Mr. Wilson became a vocal critic of the Bush administration's Iraqi intelligence. The next year, someone revealed that his wife Valerie Wilson was a C.I.A. officer, and that she suggested him for the Niger trip.

7. Avoid telegraphic language. Telegraphic language sounds like a telegram or and IM conversation: it omits less important words in the interest of saving time, space, or typing. The message can still be deciphered, but the omitted words actually play an important role: they make the language easier to understand.

There are, of course, places where telegraphic language is called for, such as in warnings.

Telegraphic

Revised

Place bait in bait pedal. Pull back bow and hold down with thumb.

Place the bait in the bait pedal. Pull the bow back, and hold it down with your thumb.

Should fader need replacing, use T-3 Torx screwdriver to open case.

If a fader needs to be replaced, use a T-3 Torx screwdriver to open the case.

Press ESC to exit.

Press the ESC key to exit the Options menu.

CAUTION: HOT!

Use CAUTION when working around here: This exhaust manifold is HOT!

NO STEP

This part of the airplane is not meant to be stepped on.

8. Ignore these approaches when the rhetorical situation demands it. The active voice is generally, not always, the better way to go. You can't always eliminate prepositions. Parallel lists can occasionally sound worse than non-parallel lists. And confusing syntax is sometimes called for by the rhetorical situation (Alan Greenspan, for instance, did very well for himself using it). The most important rule to remember is to always make sure that your work is tailored to your audience, purpose, and context—even if that means deviating from the above approaches.