The Documentation Myth

03 Sep, 2008

Commentary on The Art of Agile Development's Documentation practice.

One of the big myths of agile development is that agile teams don't document their work. I can see where that myth came from; after all, agile teams do prefer face-to-face conversations to throwing documents over a wall (conversations are far more effective) and they prefer writing maintenance documentation at the end of the project rather than at the beginning (there's less rework and it's guaranteed to be up-to-date).

There's an underlying myth, though, that is reflected in the vitriol and assumptions that comes with the accusation of poor documentation practices. That myth isn't quite as innocuous. Here it is:

Myth: Documentation is good.

People get stuck on this one all the time. It reflects a fundamental flaw in their thought process. They think: "I'm having trouble understanding (this library / the system architecture / what this tool is for)" and after beating their head against it for a while, they curse the developer and his shortsighted lack of documentation.

This is such a universal part of programmers' experience that every programmer deduces that "presence of documentation" equates to "code quality." And then she spends the next few years adding 10-line comment blocks to everything she writes, before (mercifully) realizing that ten lines of boilerplate don't add any value.

Most programmers have trouble taking the logical next step, though. Just as boilerplate comments don't improve quality--arguably, they worsen quality--the same is true of any kneejerk documentation. Documentation isn't necessarily good. It's a myth.

So... what is good? What are we really looking for when we turn to the documentation? Answers.

Forgive me for being so obvious. But changing your mindset to wanting answers rather than wanting documentation changes your entire perspective. Documentation becomes a means to an end, and not a particularly good one, either. Allow me to explain.

Reality: Answers are good.

...and the faster we can get those answers, the better.

  • Best of all is not having to ask the question: code that is so well-named and structured that it needs no comments; software whose use is intuitively obvious; libraries that scream their purpose and method of use from every API call. XP advocates this as an ideal to strive for. It's hard to achieve, sure. We don't always get there, no. But try, and when you think you need documentation, try again.

  • Next best is being able to ask someone the question and get an answer right away. Phone calls and email are okay at this, if the other person responds quickly, but the absolute best in speed and communication quality is having the person right next to you, ready to answer the question. It's not a pipe dream: that kind of instant response is why agile methods emphasize cross-functional and colocated teams. The productivity gains are amazing.

  • Not as good, but still pretty good, is being able to Google the answer easily. Sometimes I type my error message into Google, press "Search," and 500 people have experienced the problem before me and presented an answer that I can use right away. Awesome.

  • And way, way down at the bottom of the list is "reading through documentation to find the answer." Sure, sometimes documentation is beautifully organized, wonderfully written, and a pleasure to read. Yeah. The rest of the time, it's, um, not. And the more documentation you have to read before you get the answer, the worse off you are. More documentation isn't good; just the opposite. The only thing great about sheer weight of information--The Almighty Thud--is the sound it makes.

So, the next time you hear someone complaining about a lack of comments, or a lack of documentation, stop him for a moment. What's he really complaining about? Is the code unclear? Is the library poorly organized? Get those problems fixed instead. Or perhaps there's nothing wrong, and he's succumbing to the documentation myth.