Documentation in Agile Development

There is usually no need to define what Agile actually is. However, it is worth mentioning once again what Agile is not – Agile is not a methodology. Methodology defines a set of documents that must be delivered, but in Agile we “only” have Values and Principles. In terms of Agile, we are talking about an agile way of implementing software development projects, which allows you to flexibly approach the scope of the project. It can also be taken to mean a philosophy or a way of thinking and an approach to cooperation in a software engineering team. The goal is always to deliver the final product according to the customer’s business needs. Do we need documentation for it? Let’s try to answer that question. 

What about software documentation in Agile? Is it a waste of time in this approach? I have often heard that software developers do not write documentation, because they work using Agile. Is it true that we do not need documentation because of Agile? To resolve the dispute, we will refer to the Agile Manifesto, which was announced more than 20 years ago, and not everyone remembers that: 

Is there a statement that negates the need for documentation? Has the Agile Manifesto been found to lack software documentation? From what I have understood, no such statements exist. I will even venture to say that project documentation should be developed in an Agile manner, i.e. together with the software being created. 

It’s not easy to find a software engineer who likes to write documentation. Therefore, it is worth treating this task as a way of sharing knowledge. In some projects there is a role for a “technical writer”. The problem is that this is often a non-technical person. A much better solution is to extend the project team to include a Technical Business Analyst who, together with the crew, can significantly contribute to the creation of good documentation. 

The documentation preparation process can be complex – we can compare it to the example of the manufacturing industry. I used to work on software development in a non-software engineering environment. A mechanical engineer who constructs a complex mechanism first tries a number of solutions, then creates a prototype. Ultimately, in order to receive a serial product, he has to design a technical drawing in detail so that the individual components can be manufactured. Once the product is manufactured, the technical documentation is also created for the safety use approval of the device. The end user receives the manual, and the service technician receives the relevant documentation with disassembly instruction, the list of weak points, etc.  

As we see, in the manufacturing industry the documentation is therefore an integral part of the development process. Mechanical engineers have taken care of the documentation with no exceptions. In the software industry, sometimes the approach is more liberal, and we can even see some resistance against documentation preparation. 

It is always worth asking yourself what we need documentation for and why we want to create it. Is it only because we have defined the process in this way, or it is the client’s expectation? Or maybe we want to ensure the availability of knowledge in case of changes in the team? We should always keep in mind that the documentation stores the crucial information on the product, its features, capabilities and explains how the software code works and how to use it. It is a guide for future readers of the code, helping to understand how the software operates and how it should be maintained.  

We can even go further and say that documenting the code is part of writing good code. So, the reason and the goal for writing up the documentation should be the expectation to build a quality and maintainable code that can be easily readable through the documentation. 

For example, in the automotive or medical devices industry, documenting the embedded software for the certification processes is required. Therefore, the documentation must have a purpose and a recipient – simply defined by the business case. After all, we do not need redundant work that has no particular recipient and that no one will make use of. 

This way, we can adjust the creation of the software documentation, its content and the level of detail to the needs defined by the purpose of the project. Sometimes it will be a specific document describing the system architecture, processing algorithm, or just a list of errors and instructions. Another time, it will just relate to comments in the code for the person who makes changes or corrections in the future.  

The first step is to put it on the list of the project deliverables. Let us consider a use case. For example, the documentation will be needed at a later stage. Once the software is transferred to the IT department, the documentation should provide clear guidance on how to support the users. In such a case, we need to determine the requirements for the documentation upfront to meet the needs of the business users. 

The documentation development process can itself be an Agile process too. In subsequent iterations, we can consult the scope of documentation with the client or recipients, and then adjust its content and the level of information. Documentation must follow the same cycle as the entire project.  

One of the cleverest ideas in the software development process is to use collaboration and version control tools that are also designed for documentation and knowledge gathering. Those can be tools designed for collecting and controlling requirements, but also those which support the creation of good-quality code, documenting test cases, or other tools that automate and support the documentation maintenance. 

Regulatory aspects often define the requirements for processing the documentation. For example, ISO standards define the processes that should be followed when producing the documentation. Let us refer once again to a business case in the automotive industry. The software must meet the ISO 26262 standard, which defines the required documentation content and documentation management process. The standard does not determine the form, so the documentation can be produced in traditional form, as an electronic document or as a knowledge base. The standardization document emphasizes accuracy, clarity of the document structure, adaptation to the recipient of the document, verifiability, and maintainability.  

Similarly, the ISO 13849 standard relating to the functional safety of devices indicates the need for software documentation: requirements, design, and verification. Standards define not only the process based on the V-Model, but also specify content: the requirements specification guideline, evidence of the software’s security and the safety test plans and reports on the implemented mechanisms. The main goal in this case is to ensure the physical safety of the user. 

How often do you see software created without the appropriate level of documents, with an excuse that the software development follows the so-called “Agile way”? Think about what will happen once the undocumented and already-functioning software is maintained by the IT department or IT service support. It is not hard to predict the consequences of poor or incomplete documentation. 

Another miserable case is when the business comes up with an idea to extend a non-documented software product or service, and the previous team or supplier is no longer available. An extreme case (and hopefully a purely hypothetical one) would be when there is a serious accident related to the software product, and no one can prove that the safety requirements have been specified, implemented, and verified.  

Documenting work is not only good practice – it is state-of-the-art in software engineering.