One of the most common questions I get from folks looking at agile for the first time is ‘Does agile mean I don’t have to do documentation?’. I think this ‘myth’ stems from the agile manifesto value of ‘Working Software’ over ‘Comprehensive Documentation’. But the manifesto doesn’t say documentation is bad, just that working software is better.
I use two ideas to explain where documentation fits in with agile teams:
1) differentiate between ‘process’ or ‘project’ documentation and ‘product’ documentation. The first is used within the project, and once the project is over, is generally discarded or at least of little value. Requirements docs, technical specs, etc fit in here – they are expensive to develop and they need to be updated regularly to reflect emerging realities. ‘Product’ documents, on the other hand, are a deliverable from the product – they describe the product that was actually built, they have a long and useful life as part of the product, and they can be less comprehensive as they merely augment the working software.
2) differentiate between documents that ‘replace’ conversations and collaboration and documents which ‘record’ conversations. Using documents to communicate between project members is intensely expensive, laborious and ineffective (the written word is exceedingly bad at communicating complex, tacit or nuanced knowledge). People talking at a whiteboard is a much more efficient and effective form of communication. However, documents can be useful to record decisions made in such conversations – the valid characters in a field validation, the calculations to be performed to generate a report column, etc. But these are specific, explicit bits of knowledge, relatively stable, and given context by the conversation that led to them.
So in summary, I recommend confining documentation to product rather than project oriented purposes, and to write it after the fact as a record of conversations, rather than a replacement for them.