Books : reviews

Andreas Ruping.
Agile Documentation.
Wiley. 2003

rating : 3.5 : worth reading
review : 3 January 2013

There is a perception that Agile Programming can descend into hacking, and that you end up with a lot of undocumented code. After all, the Agile Manifesto says "we have come to value ... Working software over comprehensive documentation".

Here Rüping argues that this doesn't mean no documentation, it means lightweight, appropriate documentation. Better a 10 page overview that everyone reads, than a comprehensive 1000 page brick that no-one can navigate. He proceeds to give a pattern language for producing such documentation for your Agile development project. As in all pattern languages, this doesn't lead to a prescriptive outcome, but rather a process for determining what the appropriate outcome is for each project.

The advice given is appropriate to any documentation, not just that accompanying an Agile development. Much of what it says is well known (it is a pattern language, after all), but it is good to have it all in one place, written clearly, and well-justified. It is great to see a process that focuses on the quality of the documents produced. Even the patterns concerned with document appearance are pragmatic and not over-prescriptive, and are based on real research about features that enhance readability.

A must for anyone planning documentation for their project.