What about Agile Documentation?

I have been asked countless times “how is documentation managed on agile projects?” or “can you give me a template for agile documentation”. I have also heard statements like “we do not need to do any documentation when using agile”. And more recently I was asked “how do I best document an agile build as it progresses….I want to build up a picture of what it does by documenting the requirements”.

To start off, let’s get one thing straight – documentation does actually exist under agile, albeit not in a traditional sense. One of the most common misunderstandings is that agile = no documentation. Agile is not anti-documentation or agile does not disregard or exclude documentation. If you look at the Agile Manifesto, it states Working software over comprehensive documentation. Now where does it state that there is no documentation? The intent of this statement is that whilst documentation is important, the real value is producing working software that does something valuable for the business.

Anybody who actually works with code or close to the coalface knows that (overly) detailed and comprehensive documentation ages very quickly and actually becomes an impediment to respond quickly to business change as it diverges from the source of truth (the code).

One of the Agile Manifesto Principles that sums up the approach to documentation very succinctly and that is simplicity the art of maximizing the amount of work not done is essential. Let’s be pragmatic on what documents are really needed and keep it simple. Simple in number of documents needed, simple in the amount of detail and simple in the formality. Like most agile approaches, we produce just enough documentation. Keep documentation lightweight and simple – wikis are great and photos taken with a (phone) camera of whiteboard sketches often suffice.

The question you should ask yourself is what “value” does the document add to the process? What purpose do the documents serve? Who is the audience?

Documentation to aid collaboration has a different purpose to documentation that is needed for prosperity purposes. Thinking about documentation in these two types helps decides how we go about it. Documentation for collaboration should be kept as light wight as possible (and can be a thrown away when done) as we prefer people collaborating with each other face to face. Treating documentation for collaboration as if it was for prosperity often slows us down as the amount of detail and the content is quite different.

Collaboration Documentation:

Story cards
Story walls
Whiteboards
Flip charts
Wikis
Agile Management Tools

Persistent Documentation:

The code
The tests
Recorded demos
(Valuable) documents
Wikis

There needs to be a pragmatic balance of documentation (requirements, architecture, design) along with well structured, clean and readable code.

Clean code can be read, and enhanced by a developer other than its original author. It has unit and acceptance tests. It has meaningful names. It provides one way rather than many ways for doing one thing. It has minimal dependencies, which are explicitly defined, and provides a clear and minimal API. Code should be literate since depending on the language, not all necessary information can be expressed clearly in code alone.

— Dave Thomas, from Clean Code by Robert Martin (“Uncle Bob”)

This is an example where disciplined agile engineering practices is vitally important to the agile process. Don’t be afraid to rely on team member to team member communication to distribute knowledge about the system. Use pair-programming to share understanding with others so there are no dark areas and less need for people to document what has happened.

Another recent question I was asked is “how is business modeling handled in agile?” The Agile Modeling website provides some guidance. By Agile Modeling I don’t mean just UML – think ‘just barely good enough sketches’ on whiteboards – everyone should be comfortable bringing them on and in the language of the domain (ubiquitous language) – see Eric Evans’ Domain Driven Design. Domain Driven Design provides some guidance on how you think of the domain, the language you use to talk about it, and how you organize your software to reflect your improving understanding of it.

Automation of tests is important at both the whitebox (unit tests) and blackbox (functional) levels. These automated tests describe the behaviour of the system at the code level and functional level and as such by nature are a form of documentation themselves. For example, a glance through a suite of functional tests, you should be able to get an understanding of the functionality of the system. Unlike documentation, there is no fear of automated tests getting out of date as these will be constantly maintained to reflect the behavior of the system. Therefore, clean code and automated tests are seen as the primary repository of detail on how the software was implemented.

There is no one right answer as to what documentation, how to write it, and who should create it. However, constantly ask yourself before producing a document whether it is worth the effort to create and maintain it. Keep documentation simple and produce just enough. Documentation doesn’t have to be perfect – it just needs to be good enough for the purpose they serve. Once there is no use for it, stop producing it.

Related links: