RTFM? How To Write a Manual Worth Reading

Posted by timothy on Thursday May 14, 2015 @02:48AM from the use-small-words-and-friendly-diagrams dept.

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?

1 of 244 comments (clear)

Min score:

Reason:

Sort:

Re:One thing to keep in mind... by ezakimak · 2015-05-14 04:10 · Score: 4, Informative

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.