One of the common complaints that I often hear from IT leaders is that their technical staff lacks technical writing skills. Unfortunately, though, when many people take IT training, basic technical writing skills are not covered. The people who are often required to write proposals, documentation, project plans, procedures, and so on are the people who have been trained in architecture, design, maintenance, troubleshooting, and administration - but not technical writing.

The two most common complaints that I hear are:

1. Users are writing in a passive voice instead of an active voice

2. Technical documents are full of jargon

All users who will be involved in writing documentation should be required to take a general course on technical writing. In the interim, however, I’ve put together a few technical writing guidelines that users should follow.

Use plain English
Avoid filling a technical document with acronyms and technical slang
Be specific and get right to the point

Use an active voice
Passive verbs make a document long-winded
Take some time to learn how to spot passive verbs
Know how to turn a passive verb into an active verb
Keep the use of passive verbs in a technical document to a minimum

Keep sentences short
Sentences should average between 10 and 20 words
Try breaking up longer sentences into lists

Remove unnecessary words
Edit your document mercilessly
Plan to remove at least 10% of the words

Use simple words instead of complex words
Simple words make messages much more clear
Consider your audience when using complex words - make sure the audience will understand them

Avoid using jargon
The use of jargon is the most common problem in technical writing

Keep technical terms to a minimum
Easier for readers to follow

Use examples and illustrations
Ideas and information is often easier to understand when there is a corresponding example or illustration

Present information in diagrams/charts/graphs

In the next installment of this article I will look more closely at active/passive voice and how to identify the use of passive voice in a sentence.