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.