If agile is anti-documentation, why is there a manifesto?

Agile development is becoming mainstream in IT. But people new to agile often ask about the seemingly thorny area of documentation.

On the one hand, extreme waterfall-ians seem to think that documents are magical talismans. Believing that if we capture what the business say in a “tome of protection” then the business will be unable to blame us for problems. In extreme cases it almost seems like project management is more about creating tomes of protection than delivering features.

On the other hand, some agilistas claim that documenting anything will open the door to terrible bureaucracy and the end of any joy in the world. So they nervously allow words and pictures to be put up on walls, but shudder at the thought of anything beyond that. 

Interestingly, when asked why they are against documentation, extreme agilistas claim documentation is “anti-agile”. And when asked how they know documentation is anti-agile, they claim that the Agile Manifesto says it is. This is interesting because:

• The Agile Manifesto is itself a document. So if documentation is bad, then the manifesto is bad and should be ignored; and
• The manifesto also says that we are still working out better ways of doing things. So if a new document turned out to be a better way of doing things, then the manifesto implies we should adopt it to replace our old practices.

So if the manifesto does not state that documentation is evil, then what is the agile approach to documentation? 

I don’t know of any international standards on agile documentation. But I do get involved in agile projects and I do confront the question of documentation quite frequently. So these are my views:

The agile manifesto, as documented at www.agilemanifesto.org, states that working software is even more important than comprehensive documentation.  That makes sense to me – documenting a system well and then building it badly is a poor outcome.

I think we can expand a little on this concept though.

Firstly, the manifesto does not say comprehensive documentation is bad, it is actually suggests that good documentation is really useful in many cases (it states that “we value the things on the right … and then lists comprehensive documentation on the right).

But even outside of agile projects, when writing a document it is important to understand both the audience and the purpose of the document.

If we are looking for better ways of developing software, for example, then any documentation we have should be help us to develop better software.

If a project team is being asked to create better software, and is being asked to created documents as part of that process, then the team should ask if those documents really are useful to the audience (themselves) and the purpose (creating software).  If the documents are not useful then they are waste and should be abandoned.

Secondly, we should focus our effort on improving the working software we are building rather than documenting its shortcomings. If there is a choice between documenting a defect and fixing it, we should fix it; Rather than documenting work-arounds we should remove them through better design; Rather than writing user manuals, it would be better to design more usable systems; And rather than documenting processes it would be better to imbed the correct process into the system.

This means that documentation should be seen as something that supports working software rather than an end in itself.

Finally, I think that the manifesto is focussed on building better software because software is the product that its authors were discussing. But in the real world a team produces an overall solution that includes software, training, marketing material, process changes and possibly even ongoing services. 

I don’t think the authors of the manifesto meant to say “never provide ongoing services to your customers” and nor did they say “never provide useful documentation to your customers”.

So I don’t think we should see agile projects as anti-documentation. Nor do I think we should see documentation as anti-agile. Rather, I think the view of all documentation should be that it must be fit for purpose and worth completing.

So the real question is not “are you allowed to create that document in agile”; it is actually a couple of questions:

• What purpose does the document serve;
• Who is the audience for that document; and
• What is the best way to meet the audience’s needs.

At least that is my interpretation.