G+G logo   Gordon & Gordon is a partnership of two award-winning writers who specialize in high-technology, Manuel Gordon and Gordon Graham. Our clients hire us to explain complex products and to persuade demanding customers. We also share our many years of experience through practical, cost-effective consulting and training.  


TECHNICAL WRITING

MARKETING WRITING

WORKSHOPS

WORKBOOKS

DVDs

SUCCESS STORIES

USEFUL IDEAS

DOWNLOADS

ABOUT US

CLIENT LIST

AWARDS

CONTACT US

SITE MAP

SEARCH

HOME
     
10 Tips to Improve Your Documentation

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
 
Last updated:
October 4, 2002

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

TO TOP

 

   
small photo of Manny
 

How to reach Manuel Gordon

Tel: (514) 934-3274

Fax: (514) 934-6077

Email: manuel@gordonandgordon.com

small photo of GG

  How to reach Gordon Graham

Tel: (705) 842-2428 Eastern

Email: gordon@gordonandgordon.com