Sometimes, when I encounter people who can't stand the idea of agile methods, "lack of documentation" is one of the things that they choose to scoff at.

"How can you possibly think that software could be developed without documentation!?" they cry, remembering the excrutiating pain they've been through while trying to understand some poorly documented piece of software.

This misunderstanding, I think, stems from the word "documentation." If we use "communication" instead, the agile approach starts to make more sense, as I'll demonstrate.

Broadly speaking, projects need two kinds of communication: communication to get work done and communication to enable future work after the project is over.

Get Work Done

People need to communicate to get work done. On a non-agile project, this communication is usually facilitated through documents: requirements documents, architecture documents, design documents, etc.

This is the kind of documentation that agile folks try to eliminate. Face-to-face communication is generally more effective, as Alistair Cockburn discusses (look for Slide 3). Since agile teams emphasize people working together, they find that they can replace documentation with other approaches and do the same work more quickly.

Enable Future Work

The second kind of communication is historical in nature: it explains why decisions were made, allows new team members to come up to speed quickly, etc.

Historical communication (for lack of a better term) degrades rapidly when done face-to-face. Teams with a strong culture can sustain an oral history for a little while, but that history will fade as the team members move on to new things. Written documentation works much better here. (Alistair Cockburn also suggests videotaping a whiteboard discussion, an intriguing idea.)

I think it's this kind of communication that the "Gasp! No documentation!?" crowd is afraid agile processes lose. I disagree.

First, let me say that I completely agree that documentation to enable future work is necessary. For traditional processes, this documentation is produced as the team progresses, as a natural byproduct of writing documents to get work done.

But... this is important... it's not produced well. What happens is that the "get work done" documentation transmutes into "enable future work" documentation. But by the time the project is over, that "get work done" documentation is usually quite out of date, because people were too busy getting work done to update it every time they made a minor change. The cumulative weight of those minor changes often leads to documentation that's unreliable.

Instead, what agile practioners recommend is that "documentation" tasks be added to the plan--often at the end--so that the documentation that's needed for enabling future work is done specifically for that purpose. I've done this and I can say with confidence that it's much easier to write, doesn't take nearly as much time, and (in my admittedly biased opinion) produces higher quality results.

Those Darned Details

As always, of course, the devil's in the details. Agile teams don't just throw away documentation: they replace it with something else. You can't just stop writing comments: you have to have simple design, tests that show usage, and self-documenting naming conventions. You can't just throw away the design document: you have to have simple design, regular team discussions at the whiteboard, and merciless refactoring.

Similarly, the advice to create documentation to enable future work is well understood by expert agile practitioners, but I don't think it's a meme that's in general circulation yet. We can do more here.

In general, though, the agile approach to documentation is quite pragmatic: when it comes to getting work done, replace written documentation with more efficient forms of communication. To guide future work, create documents at the end of the project, when everything is complete, well understood, and easy to document.