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?

Comments

OSS needs technical writers more than coders

[NotDrWho]

Coders they got. Projects whose "documentation" consists of anything more than a technical list of bugfixes they don't.

OSS needs to realize that well-written documentation is just as important as well-written code.

Re:OSS needs technical writers more than coders

[Maxwell]

Incorrect, and arrogant. It IS hard to write well, it is a skill, it can be learned, and not many in the tech community have it.

"It isn't hard to code well, it just takes time" - said no writer, ever.

Re:OSS needs technical writers more than coders

[NJRoadfan]

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.

Re:One thing to keep in mind...

[Anonymous Brave Guy]

Make it conversational as well as informative.

On a related note, often with OSS there are more than two parties in the conversation.

If I'm configuring some sort of local mail store, I don't just need to know how to set up Dovecot. I need to know how to set up Dovecot, Postfix, Roundcube, and so on, and I need to know how to set them up together.

If I'm configuring some sort of Linux server, I don't just need to know how to set up RAID, I need to know how to do it with logical volumes for future-proofing, and I need to install a bootloader that understands. And then I need status monitoring, and procedures for recovering after failure, adding more capacity, and so on.

Frequently with OSS, particularly sysadmin-type stuff, I find there is more detail than you would likely ever need about any one part of the system, but the real problem is figuring out how to connect it all up in practice.

Re:One thing to keep in mind...

[Anonymous Brave Guy]

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.