Writing Documentation

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.