Summary

• Supply a real (dead tree) manual.
• Explain the problem begin solved.
• Present the concepts, not just the features.
• Cover the task domain, not just the operation of the program.
• Make it enjoyable to read.

Acknowledgements

Summarised from Bruce Tognazzini's website. This is the only writing I've located (so far) about producing good documentation.

Write the F***ing Manual

Telling users to RTFM doesn't help. Fixing the manual does. Follow these five easy steps:

1. Supply a real manual. A real manual (if you didn't know) is made of dead tree. Electronic documents don't cut it. They aren't physically portable (like a book) and they are difficult to read (lower resolution).
2. Explain the problem begin solved. Don't just reformat the design specs and print them. A list of features/functions is just as bad. Humans find it extremely difficult to store free-floating information. Explain a problem and offer a solution and people will remember it forever.
3. Present the concepts, not just the features. Give the user the framework to hang the details on. Any time you learn a new piece of software, you go through the process of constructing a mental model of the software, what Don Norman calls the "User Model". Building a model requires a framework, and the framework consists of these large, key concepts. Without a framework, it is extremely difficult to learn.
4. Give them more than they deserve. Manuals need to cover the task domain, not just the operation of the program. (That doesn't mean that a tax planner manual needs to cover the entirety of tax law.)
5. Make it enjoyable to read.I can't help you there.