
Rules for Writing Technical Documentation (2009) - Tomte
http://www.developer.com/tech/article.php/3848981/The-7-Rules-for-Writing-World-Class-Technical-Documentation.htm
======
FiddlerClamp
As a technical writer, I have a few quibbles with these points:

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.

------
infocollector
Is there a better version of this in 2016 somewhere?

~~~
hkmurakami
A friend of mine wrote a short ebook [1] on the subject, and I [2] thought it
was excellent. He's currently a lead technical writer at Palantir.

[1] [https://www.amazon.com/Modern-Technical-Writing-
Introduction...](https://www.amazon.com/Modern-Technical-Writing-Introduction-
Documentation-ebook/dp/B01A2QL9SS)

[2] I wrote a lot of Fluentd's documentation in its early days
[http://www.fluentd.org/](http://www.fluentd.org/)

------
davidgerard
the opposite:

HOWTO: write bad documentation that looks good

[http://thelaird.us/k5/section-
slurp/k5-tech/2003-9-29-104212...](http://thelaird.us/k5/section-
slurp/k5-tech/2003-9-29-104212-112.html)

(archived from kuro5hin)

------
nickpeterson
Much like code, good documentation is concise and direct. Refactor your
documentation until it's clear.

