• BlogNav:
• Archive of all posts

The Documentation Conundrum

Posted: Mon, 26 December 2005 | permalink | No comments

Several times over the last few months, I've had a common experience: I write documentation (gasp!), and then nobody reads the damn stuff.

This offends me primarily because (like most geeks) I despise writing documentation. However, I write it because I despise having to explain myself a dozen times over. Better to write it down, and then I never have to worry about it ever again. Then, after I've taken the effort to actually document something, nobody reads the stuff, and they just ask me directly -- and then get offended when I grunt "RTFM" at them and go back to my code. But you start to think: "why am I wasting my time reading these docs, when I could just save myself a few hours of my life and answer their questions as they appear?"

Now that I've gotten into the documentation habit, lack of documentation elsewhere also offends me. I want to know something, so I go looking for some form of written expression related to the topic at hand (Google Is Your Friend) and come up completely dry. For free software, I can more-or-less live with it -- I follow TechnoYoda's advice, and Read The Source, Luke (and then document it). For other stuff, though (lock-in software, social processes) I've got no hope. I'm reduced to pouting in IRC channels until someone tells me what I need to know (and then I document it). But you start to think: "why do I waste my time looking for documentation, when it never exists anyway, and I could save myself some time by just asking directly in IRC or on a mailing list?"

As we all know, there are two documentation-related universal truths in IT:

1. Nobody ever writes documentation.
2. Nobody ever reads documentation.

I got to thinking -- is there a causal relationship here somewhere? Did people write documentation in the olden days, but gave up because nobody ever read it, or did people originally always read the manuals, but stopped looking for documentation because it never existed (or when it did, it was content-free and useless)?

Or did both of these truths appear independently, or are they both aspects of a single truth: "Everybody Hates Documentation"?