Here is a bit of tech-writing humor, courtesy of PlainLanguage.gov (http://www.plainlanguage.gov/examples/humor/technologywriters.cfm). This helpful website gives tips for writing clear, readable documents. It also reminds us with humor what NOT TO DO when developing technical documents.

Lesson One: Style

Acronyms

Any term with at least two words must be assigned an acronym, and it must be defined in parenthesis, even if you’ll never use the term again. Remind your readers what an acronym stands for at random intervals. If you’re not sure how often you should insert these reminders, just define the acronym every time you use it.

Bulleted Lists

There is simply no way to include too many bulleted lists. Bulleted lists make everything more clear, because it takes a complicated sentence with too many commas and turns it into a simple and precise enumeration of critical points.

Example:

• My dear Elizabeth,
• The weather is beautiful; and,
• I wish you were here.
• Love always,
• Angus

Colloquialisms

Colloquialisms make a document more understandable to more people. Use them as often as possible. When using a colloquialism, set it out in quote marks, then define it for good measure.

Example:

It was raining “cats and dogs” (i.e., it was raining so hard that it seemed almost as if domesticated animals (e.g., cats and dogs) were falling from the sky rather than raindrops).

Numbers

Be all-inclusive. Write out all numbers, then follow with numerals in parenthesis.

Example:

I own fourteen (14) cats.

Lesson Two: Grammar

Commas

Commas are a sign of weakness. Good sentences are clear without the use of commas. Bad sentences use commas as a crutch to help readers limp along. Rewrite any sentence that requires the use of a comma. If all else fails just take the commas out of the sentence without changing anything else. Occasionally sprinkle a few commas into the document at random just to keep the English-major weenies happy.

Passive Voice

You’re better off with passive voice. Active voice annoyingly insists on placing attribution to actions, and we all know that sooner or later somebody’s going to get fired for being attributed to something. English-major weenies insist that passive voice is bad, but that’s because they have no real authority and therefore are in no great danger of getting fired for anything. Put them in management and see how quickly they adopt passive voice.

Semicolons

This is the Mystery Punctuation. No one can use this properly, not even the English-major weenies. But semicolons make a sentence look impressive, so use one in place of a comma every now and then (that is, if you still use commas; see “commas”).

Lesson Three: Technical Terms

Functionality

Use this versatile word in place of a word like “function” or “feature”. Those words are overused, so functionality will make your document seem fresh by comparison.

Example:

Do you have the power windows functionality on your car?

Impact

This is another wonderful word. Use it as much as possible! Any time you have an opportunity to explain that an action causes something to happen, be sure that it was an impact. Never write:

Turn the computer on.

When you could write:

Utilize the power on/off interface to impact the operational status of the system.

Summary

Now that we’ve reviewed what NOT TO DO in technical writing, please visit some of our other blogs for GOOD writing samples by Phoenix Tech Pubs staff members.

Andrea is a Senior Technical Writer at Phoenix Technical Publications. Phoenix Tech Pubs has provided complete technical writing and documentation services in the San Francisco Bay Area for over 25 years.