Notes In The Margin

Although I've known for a while that it was possible to build the HTTP Server docs as PDF, I never really bothered to find out how. Finally this afternoon I was poking around and figured out how. The latest docs are available in PDF format here, and I'll try to keep them somewhat fresh, if you want to bookmark that.

Apache HTTPd 2.0 docs (pdf - 3Mb)
Apache HTTPd 2.2 docs (pdf - 4Mb)
Apache HTTPd 2.3 (trunk) docs (pdf - 4Mb)

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.

Someone (and I now can't remember who - I think it was Philip Olson) pointed me to Writing Open Source this week, and I've been somewhat fixated on it since.

I've been writing technical documentation for more than a decade now. 12 years sounds about right. Let's go with that. I've been told I'm good at it, so I keep doing it.

I'll let you in on a little secret. I don't tell just anybody this, because they think I'm a freak. I actually enjoy writing documentation. I enjoy figuring out how things work, and then writing about it so that other people don't have to figure it out. I enjoy catching the first glimmer of the spark of understanding when someone reads what I wrote and gets it for the first time. I love it when people say "Oh! I didn't realize it was that easy!" and "Why did it seem so complicated before?"

There are precious few places that do documentation well. There's a number of places where Open Source documentation, and software support in general, typically falls down.

* Tell the user that they're an idiot, and probably too dumb to use this software. This is done in a variety of ways, and is often abbreviated RTFM, but TFM is often insufficient.
* Pretend that the end-user cares about the architecture of your software. They don't. They just want to get their job done.
* Fails to distinguish between end-user and developer documentation, and, if there is a distinction, the path from one to the other is left as an exercise to the reader
* Refuses to consider the interrelationship with related technologies, and continually tells the user that "that's a problem with ProductB" rather than giving them the support that we're qualified to give.

And many, many others.

As I looked at this website, I became more and more persuaded that perhaps I could help in the effort to write a guide of how to write Open Source documentation - not from the perspective of whether to use passive voice or not, but from the perspective of identifying with your audience and answering the questions that they're actually asking, not the ones that you feel that they should be asking.

On a related note, during a recent conversation on IRC I suddenly realized that I've been working programming jobs all these years because I haven't been able to find a position that'll pay me to do what I really love - writing technical docs. I wonder where this realization will take me in coming years.