I've been delighted to see the "Write a better FM" meme that's been spreading slowly through various blogs. I understand that I'm to attribute this to Kathy, but I've been saying this for years. It's not sufficient to tell people to Read The Fine Manual, you have to actually listen to the questions that they are asking, and make sure that TFM actually answers them. And, if it doesn't, then make it better.
This is sometimes as easy as it sounds, but usually isn't, for reasons that are often non-obvious to people that are in a place to make the world better.
It's too hard to make the docs better. Those of us who are involved in documentation need to:
- make it easier for folks to tell us what's broken
- be less defensive when they suggest ways to fix it
- clearly identify our audience and listen to their problems
- provide clear, correct, efficient ways for them to achieve their goals, rather than telling them that they have the wrong goals
If we don't, what happens is that a thousand stinkweeds bloom. I'm discovering this the hard way with mod_rewrite. Because the documentation for mod_rewrite is so intimidating, and folks don't know how to contribute changes to it, instead they write hundreds of HowTos and tutorials and recipes and rants about how to do things in mod_rewrite. These articles are, for the most part, wrong. The ones that work, often do so by sheer chance, and are prone to break if attempted elsewhere. But desperate users take these tutorials, hack on them until they mostly work, and they pass their hard-won ignorance on to other folks.
We could have prevented this, but we chose, by our inaction, not to do so. The problem is *much* harder to fix than it would have been to prevent.
I'm thinking about better ways to allow end-users to tell us that the docs suck, or to suggest improvements. I've never been a fan of the PHP methodology, which I have at times called "Scripture With Commentary", primarily because so much of the commentary is crap. However, it gets the job done, and seems to be the best of the bad. I'd love to hear your suggestions of better ways to collect user feedback, and, perhaps more importantly, incorporate it into the end product.
PostgreSQL offers the same possibility, compare http://www.postgresql.org/docs/8.4/static/ and http://www.postgresql.org/docs/8.4/interactive/
I actually do like the approach as the comments often have more insightful examples, or explain an aspect that's been left out because for the author of the documentation it was clear to begin with.
On the Apache/httpd front we have the wiki, but I find it's usefulness so far rather limited: One of the aspects missing is a discussion platform.
The trick is regular gardening. Someone has to go through all of those comments, decide which ones are insightful, figure out how to add that information to the document, and purge the noise. If there's more than, say, a dozen comments, it becomes just noise, because it's too hard to weed through them to figure out which ones are worth trying. This is a great space for volunteers, but there's very little glory in it, so it's a hard sell.
Can we be more open to feedback to improve the FM, without having to weed through more noise? It seems like that might just be the price of inviting more feedback.
One thing that can be helpful is to find a novice and sit down with him/her. Inexperienced people sometimes identify the most basic problems!
I do that every single day. It's called IRC.
If you want more user friendly docs then you should start with informing your readers of what "FM" means!