The Agile method is being widely adopted by public and private organizations as a way to manage their digital transformation projects. One of the method’s aspects that raises a number of questions is project documentation in the “Agile way.” In this article, we’ll take a closer look at this critical topic, which is too often neglected in Agile development.

Written by Charles-Olivier Mercier, Agile Coach at Cofomo

First, it’s important for the team to determine the purpose of the documentation being produced, its usefulness and the users who will benefit from it.

If you focus on the execution phase of an Agile project, documenting user stories is usually sufficient for a team to understand the project’s requirements and to develop a functionality. Story documentation can take the form of functional requirements or acceptance criteria, but a team may also want to document technical specifications, such as when it carries out behaviour-driven development (BDD).[1] 

Once the stories are completed, permanent documentation can be designed to ensure that all new team members understand the choices made and their context, as well as the reasons the product works the way it does. This more lasting documentation should be brief so it’s easy to digest and enables people to quickly understand how a product works. You should aim for simplicity and efficiency.

What’s the best format?

There isn’t a prescribed format for the documentation created for Agile projects. This flexibility may be welcome, but may also raise its share of questions.

For example, if a team or an organization usually produces a certain type of deliverable (in terms of format, construction, tools and so forth), then adjusting the way it produces documentation may require some reorganization and some effort. You will need to review the documentation, as it is being drafted, to ensure that you only keep what’s essential for the project team. The time you invest in adjusting your documentation method will be worthwhile, as it will lead to time savings, improve the use of documents and increase the comprehension of those who use them.

The new format can be based on existing procedures, as long as you streamline them and eliminate any parts that aren’t relevant to users. The primary aim is to produce documentation that presents the key elements and is easy to follow.

For example, you may be using deliverable templates in your company without anyone ever questioning the usefulness of documenting certain sections. That means that sections containing irrelevant information are being documented—and no one needs them! As a result, the useful information is diluted and those creating the sections are doing unnecessary work. By adjusting this type of deliverable, you will ensure that the documentation is both easy to produce as easy to use. It will also prevent a potential asset for the organization from becoming too difficult to maintain, or from containing redundant information.

When’s the right time?

We’ve already mentioned the importance of documenting stories during the development process. By doing so, team members will understand the requirements better, communicate them more clearly, and work together more efficiently.

What about permanent documentation, which will be kept and used as reference material for the duration of the project? For Agile projects, decisions can change quickly, so it’s a good idea to keep a history of decisions until they have stopped changing. Often, this phase of maturity of the functionalities (or of a project) is only reached during the development process, such as at the end of an iteration or when a functionality has been delivered and is already being used in production. This is the time when teams should focus their efforts, and be sure to document the decisions on functionalities that will no longer change. This situation is captured well in Scott Ambler’s “Disciplined Angel” toolkit:

While this example works for many teams, it’s difficult to apply it to teams that use continuous integration or continuous delivery. These teams generally manage to optimize all of their development processes, and must produce documentation quickly and regularly. They can then use tools such as Sandcastle, which is designed to dynamically generate documents from code.

How can you help your team achieve its objectives?

These days, we have a wide range of tools for collaborating in real time (Confluence, Azure DevOps Wiki, etc.); and these tools can even generate documents dynamically. All of them are designed to make your life easier. It’s up to you to determine how you’d like to use them.

Once you have defined the structure of the documentation, focus on how the teams can be organized for maximum efficiency.

One possible best practice is to include documentation efforts in the Agile execution process, such as in the “definition of done”. By working in this decentralized way, you will ensure that everyone understands the documentation requirements, and its quality will become a common goal.

In every case, if a team wants to make changes to its work methods and processes, it will need to ensure that everyone understands their importance to the quality of documentation produced and in the “definition of done”. The strength of multi-disciplinary and self-organized Agile teams lies in their capacity to decentralize certain responsibilities, such as documentation, rather than assign them to specific roles (e.g. analysts or architects). Documentation then becomes a shared task and if adjustments are needed, the team will need to find the best way of working.

Adopting this streamlined, more agile approach will have effects that will take some time to adapt to. The only way to strike this balance when it comes to documentation is, ultimately, to try it out, learn from your mistakes and continuously adapt your approach!

Conclusion

In closing, Agile approaches are not prescriptive. Rather, they recommend the use of minimum documentation based on the needs of the team or organization.

Approaches such as Scrum are development frameworks rather than dogmatic methodologies. They leave room for teams to be creative in finding solutions that best meet their needs. Those solutions may be the result of streamlining existing documentation, or they may take a completely different form.[4] 

It’s important to remember that it’s up to the team to define its needs and determine how the documentation should meet those needs.

Lastly, keep in mind that the emphasis should be on software development, not on the documentation. As mentioned in the Agile Manifesto,[5] documentation does not add any value without the product it supports.