Documentation? What Documentation?

One of the biggest misconceptions within agile teams is that we do not need documentation. Also, many teams struggle to get to grips with documentation that is needed within agile projects. When implementing agile for the first time, many teams actually drop the ball before realising that some sort of documentation is still needed within agile projects.

The approach

So the first approach is the following:

When starting with agile you can still use exactly the same documentation that you were using when running non-agile projects. The only thing that really changes is the approach you have in compiling the documentation. In agile, we build software incrementally and so we focus on doing the documentation incrementally and the focus changes to describing the specific set of requirements that is developed for the next 2 weeks and not the whole solution upfront.

We although have identified a set of useful agile documentation that is more suited to agile projects than the documentation used during normal non-agile projects.

Agile documentation that adds value

So another more agile approach is that we look at useful agile documentation that adds value and we use the following criteria when deciding if the documentation adds value:

Agile documentation Criteria #1:

We ask if the document will be useful to the team or any client after the delivery of the project. If the answer is NO, then do not do it. A typical example is the thick word document specs we all have seen before. These documents never get updated with the changes that occur while developing the solution, so by the time the project is delivered the information in these documents is outdated. This means that no one will consult the documentation again as it does not describe the actual requirements implemented within the application.

Agile documentation Criteria #2:

We would like to stay away from using thick Word documents to describe agile requirements. As the implementation team, we often need to read through these thick documents and extract the information that will actually be relevant to implement. These documents often serve a purpose of keeping clients happy and to use it to cover our backs. As agile is about open, transparent and trustful relationships between parties involved, this does not really serve a purpose anymore.

Agile documentation Criteria #3:

Artifacts that help to describe the requirements to clients or the implementation team in a clear, simple & precise way are very useful agile documentation.

Agile documentation Criteria #4:

Artifacts that help to describe the requirements to clients or the implementation team in a visual way are very useful agile documents.

Agile documentation Criteria #5:

Artifacts that help us to complete acceptance testing on the delivered solutions are very useful agile documentation.

Agile documentation Criteria #6:

Artifacts that help us to understand a complex ecosystem of systems and solutions are very helpful agile documentation. This does not only aid understanding, but it aids us to get new employees up to speed within the organization quickly.