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?
Strongly disagree, documentation should get straight to the point.
Detailed reference documentation, yes.
But more often than not, the problem with OSS seems to be that no-one wrote the introduction/overview/big picture stuff, and the developers instead expected that users would just magically discover that kind of understanding from 1,943 man pages with cryptic names and no context or navigation to show them where to start.
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
I am in the process of documenting a system I added to an open source project. Its not easy to write, particularly if one doesn't have a background in technical writing. The basic process the same though, you have to write for your audience, and revise.... a lot. In my case, I have been sending drafts of my work to other developers in the project to not only proofread, but to actually read through the directions and perform the listed tasks as an end-user would. So far the feedback has resulted in changes in both the documentation and the program to make things easier/clearer for the user.
I guess what I'm trying to say is, don't skip review and just post the documentation. Give the documentation and software to someone not familiar with it and see how they interpret and understand it. Listen to their feedback. Way too many developers don't (I'm looking at your Google!). Wikis are supposed to address this, but don't seem to engage enough people to actually contribute.