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?
TLDP had a lot of problems and they weren't all internal to TLDP. I think the biggest one was that we were trying to balance between documentation style and authoring while trying to make it easy for people with little documentation skills to write. It isn't as easy as writing a word doc and uploading it - we were trying to make it so you could read documentation on any format: PalmOS, PDF, Word, printed, HTML. Docbook and linuxdoc made that process easy, but it was a markup language and the best way to write it was as by doing the markup yourself (think writing HTML by hand) and there was a lot of infighting about going back to linuxdoc. As the documents became more complex it was difficult to do technical reviews since a lot of the people were more documentors than technical. As Linux grew and advanced, nobody was available to update old documentation because they were working on new ones, so much of the existing content became stale.
I totally agree.
I've seen countless man pages that don't even bother to say what the command *does*, let alone *why* you would want to do that. They assume it is all self evident (I'm guessing the author's logic was: "or else why would you be reading about the flags if you didn't already know you needed it and for what?").
Also, sometimes explanations are vague--being precise about the behavior (especially if it is altering data) is important.
This is what happened to the "For Dummies" books, IMO. The old classics like "DOS for Dummies" was great for a beginner, but it seemed like a lot of the later books went way too heavy into the realm of comedy or stretched tangential analogies, and it distracted from the key information itself. ;)
Nobody likes dry reading. but they got soppy dripping wet.
Look back up at my post, now look back down, you're on the Internet. Now look back up. I'm a signature.
One of my favorite sets of open source documentation are the perl man pages. They are written in an informal yet instructional style, and are *loaded* with useful, practical examples of how to use the language. Heck, I refer to "man perlretut" even when I'm not using perl, but I need a general reference for regular expressions. Sooooo useful!