Slashdot Mirror
RTFM? How To Write a Manual Worth Reading
An anonymous reader writes with a link to Rich Bowen's insightful, detail laden piece at Opensource.com about improving documentation: Have you noticed that the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be? I've been contemplating this for years, and have concluded that this is because patience and empathy are the basis of good documentation, much as they are the basis for being a decent person. What's the best example you know of for open-source documentation? How about the worst?
What I've learned from decades of reading professionally-written manuals can be summed up in two steps:
The first step in writing a good manual is to have a very weak grasp of the language used by your target audience. It is important to use many grammatical and spelling errors, just to make sure the reader stays on their toes and pays attention. Research has also shown that users do not like to read manuals that use advanced vocabulary or complex grammatical structures.
The second step is to manage the density of information on the pages properly. A piece of paper is pretty large, and so are most screens, so a lot of information can be included on a single pane of view. It is important to make the most of this space and convey as much information as possible, as densely as possible. The more information a user can see without having to turn pages, the better. Use of separating devices, indications, and other correlative marks should be avoided, as it takes away from space that can be used for more information. They also can cause there to be more whitespace on a page, which should be avoided at all costs.