Rules for Writing Technical Documentation (2009)

1. Dry sucks...but humorous can be worse.

In the mid-90s, I worked at a company that used a DOS add-on to fax from an accounting program. One day we were in a panic because it wasn't working properly, so we dug out the manual. It was all of 10 pages, the last of which was a list of jokes about 'How to Safe Fax' (as in safe sex).

Similarly, I've heard of a government system from the 80s that would display animated monkeys onscreen when an error occurred, and another program with the classic error message "Oopie!".

Humor has no place in documentation.

I think of technical writers like other professionals - doctors, lawyers, etc. Often, you consult a professional because you're in a crisis: you're sick, you're facing a lawsuit, or you can't get a program to work properly.

Research shows that 80% of people don't refer to documentation at all until there's a problem. So when someone's reading documentation, it's a good bet they're in a crisis.

Humor doesn't help. When a reader needs assistance or is in a crisis, humor can come across as silly or insulting.

Humor can also confuse, especially if the reader's first language isn't the same language as the documentation. And lastly, humor makes translation and internationalization harder. Some concepts don't translate across cultures.

2a. Before you start, make sure you understand your audience.

This is the key starting point for technical writers. Who is the audience for your documentation? Is it the average end-user, a developer, a system administrator, or someone else? Once you know your audience, you'll know what information they need spelled out and what they already understand. You'll also know what they'll be looking to achieve, and how you can write documentation to help them meet their goals.

5a. Use illustrations only when necessary.

Illustrations and diagrams can be costly to create, update, and translate. Don't use them when a list or table would do the job.

I would add the following two points:

8. For longer documentation, always include a revision table at the beginning of the document. This helps readers (and writers who may update your materials in the future) to understand what changes have occurred.

9. Identify external hyperlinks that do not link to URLs. For example, I would write a hyperlink to a PDF as <hyperlink> (PDF, 3.6MB). This provides the reader with a preview of what they can expect to find.

HOWTO: write bad documentation that looks good

http://thelaird.us/k5/section-slurp/k5-tech/2003-9-29-104212...

(archived from kuro5hin)