Wednesday, August 11, 2004

Technical Documentation Tips

Technical Documentation includes the writing of owner's manuals, service guides, how-to articles, intranet punch lists, keyboard shortcuts, help desk information (like Macromedia RoboHelp X5), product comparison charts, and product specifications.

The principles in writing Technical Documentation are not very different from direct marketing, web site content writing, email composing, or any form of efficient written communication.

All the fundamental rules still apply, but there are also some distinct guidelines to consider when developing Technical Documentation.

Here's a general laundry list of things to consider:

Technical Documentation Tips

1. Keep it simple, short, and scannable.

2. Put fast instructions on one side of a page, then "How to Correct Errors" type detailed information on reverse side.

3. Be consistent with words and phrases. Don't use "click on File" in one place, then "mouse select File" in another place within the document.

4. Use numbered or bulleted lists, with bold for headings (Step 1, Step 2, Step 3, etc.) and indentations for supplemental details.

5. Abstain from using long sentences. Avoid dense paragraphs. Use easy to read formats, no matter how complex the instructions may be. Simplify and shorten.

6. Add white space between sections and distinct sets of instructions.

7. Consider various versions of the same documentation. For example, distinct versions for:

***Managers (short, to the point, general overview, who to contact for more information).

***Customer Support Personnel (like 800 number tech help, similar to End User version) .

***Sales Force (so they can explain the basics to prospective customers, technical documentation and help systems are nice product features and sales points).

***End Users (walk them through each step, in language they'll understand).

[NOTE: I can't indent with tabs on this blog, so I devised a "work around" solution: three asterisks.]

8. Don't omit what you might consider "obvious" or even "dumbed down." Much technical documentation leaves out steps that the writer just assumed the readers would automatically know and do. Often left out are things like "click Accept or click Decline" and "press Enter."

9. Check your instructions to make sure they work and don't leave anything out. For example, you may read the help instruction "then click on My Resume" but there is no "My Resume" button appearing...until you click on something else first.

10. Set up a documentation template for consistency of organization and presentation.

11. Use command words at beginning of sentences for each step. For example, what I'm doing in this list:

***"Keep, Put, Be, Use, Abstain, Add, (etc.)"

12. Start documentation at the beginning, square one, ground zero, not assuming users are already at a certain point into the process.

13. End documentation at the final step, the end, the very last thing to do...not assuming users will reach that point on their own. For example: "Click Turn Off Computer. Disconnect modem. Put dust cover over keyboard. Make sure printer is turned off. You may now go about other business...or go home." This may be a bit much, but you get the idea.

14. "Smarting Up" and causing some newbie or low-skilled users to not understand can be worse than "Dumbing Down" and causing some advanced or high-skilled users to be impatient with "obvious" details.

15. Provide adequate white space for users to add their own notes, further questions, or personal short-cuts...and for tech staff to date and initial their approvals.

16. Consider using serif type fonts for print media documentation...sans serif type fonts for web/computer screen documentation.

17. Give documentation to newbies, children, elderly, strangers off the street, or computer illiterates to test the simplicity and clarity of your writing. If these types of users can succeed with your documentation, it's probably well written.

18. Observe end users testing your documentation. Make notes on what they say and do.

There's much more that can be said on this topic.

More later.

Stay tuned to Vaspers the Grate.

No comments: