Documentation in an Agile Process

One of the more common misconception about agile is to think that it means no documentation. In the original Agile manifesto we can find that we value:

Working software over comprehensive documentation

For some reason people mistook this to mean that documentation has no place in an Agile process.

In my opinion this is very far from the truth. What I do agree is that the commonly form for documentation i.e. text files, that most people mean when they say documentation, is probably not the best way to get the job done.

Why do we write documents?

I recently had a nice discussion with Eyal Katz about the need for documents. Eyal listed the following three reasons:

1. To make the writer really think about what he is writing about. For example by writing a design document the designer is forced to think and formalize his design properly.
2. Documents can later on serve as a mean for sharing knowledge.
3. To store knowledge (so we wont forget)

Are documents cost effective?

well in my opinion the answer is clearly no (in most cases):

I myself think better against a white board. For me sitting against a computer screen is just not flexible enough. When I do a design session using a white board, I usually complete in an hour what can then takes me 3-4 days to write down. So clearly, for me, writing a text file is not the most efficient way to think and I'm sure other people have even better ways.

But how can other people read/understand what I sketched on the white board? Well they cant. But generally it doesn't take me more then a 20-30 minutes to explain it. So instead of spending 3-4 days writing it down, I can personally teach it (and trust me its much more effective that way) to 60-80 peoples in a 1 on sessions. So how many people are really reading most of the documents we write?

but what will happen in a year from now if I don't write it down? Well, the real problem is that without maintenance documents gets outdated. Wherever I go, I see that knowledge stored in text files is almost always either partial, old or just plain wrong. For some reason software companies don't do a good enough job in making sure that their text files reflect reality.

No documentation in an Agile process?

on the contrary  a lot of documentation, just not a lot of the regular kind (i.e. text files). Some examples:

• Product & Iteration backlogs serves as a good place to specify requirements.
• Unit tests serves as good low level design documents
• Burn down charts serves as great progress reports.

When taking into account all forms of documentation an agile project will usually have a lot more documentation then seems at first sight and in most cases that documentation will be more accurate and effective.

Uninstall Word?

All this does not mean that good old text file don't have their place. Just to say that from my experience they are widely misused. Knowledge stored on paper (or in files) is far less important then knowledge stored where it counts in people heads. A true Agile project will first make sure that it gets to there before it goes into a text file, and not vice versa.

Posted in: Agile practices.,Documentation,Random Thoughts