by Gordon Graham

If you're new to the world of technical writing, here are some tips for how to improve your documentation.

1. Get a grip on your audience.
Find out the age, knowledge, role, and motivation of your users. Then slant your documents to your intended audience.

2. Describe tasks, not features.
Tell your users how to do what they need to do, not how your product works, or why you designed it the way you did.

3. Show, don't tell.
Most people can grasp and recall pictures better than words. Include diagrams, icons, and screen shots to help anchor your message.

4. Downsize your documents.
Ask yourself: who really needs to know this? When in doubt, leave it out. The thinner the book, the more likely people will pick it up.

5. Root out the passive voice.
"B is caused by clicking on A." = passive voice.
"Click A to do B." = active voice.
Using the active voice will save words, and help downsize your documents by a good 15 per cent!

6. Help users find it fast.
Always include an index in print, and insert adequate keywords in online documents. Rule of thumb: an index should be 5% as long as the text. So that 300-page manual needs a 15-page index (or 7-8 pages at 2 columns each).

7. Go paperless!
Push paper into online help, onto CD-ROM, and onto the Web. You'll save on printing and shipping. And your information will be easier for your customers to search electronically.

8. Design graphics and icons with care.
Watch out for symbols and colours that won't work--or could even offend--in other cultures.

9. Develop a style guide.
Keep notes on your standard spelling, phrasing, and formatting. For consistent results, make an electronic template for all your writers to share.

10. When in doubt, hire a professional.
You'll get better results when you hire a seasoned pro to plan and write documentation. That means better reviews, happier users, more sales, and more profits.

How to Contact Us

Entire contents
© 1999-2006
by Manuel Gordon
& Gordon Graham

TO TOP