Documentation is still too often seen as superfluous or as a constraint. On the contrary, adopting a Documentation-as-Code approach offers a potential gain in time and efficiency for teams in an Agile context, in particular, to ensure the continuity of the code and the software infrastructure.
1. What if the documentation was part of the source code?
Documentation is often a delicate subject in an Agile context. Based on the second principle of the Agile Manifesto: Some consider “Functional software rather than complete documentation” as counterproductive. However, in my opinion, this principle does not mean that documentation is unnecessary, but rather that “you must not sacrifice the quality of the software to produce it.”
Naturally, the team’s primary objective is to produce the software, and the aim of the members recruited later is to maintain and modify this software. But how could they achieve this without documentation? You could say that the code in itself must be sufficient to understand the essentials … but even when the name of the objects is explicit and well-chosen, that is far from being enough. However, the problem is that producing and maintaining documentation takes a long time. So one solution could be to consider the documentation as part of the source code.
2. Good documentation practices
But before discussing the concept of Documentation-as-Code, I would like to share a personal experience that I think may sound familiar to you. A banking solution provider employing both service providers and interns had experienced high staff turnover over a very short period. Applying the principle that documentation is only written when several people ask for it, it was practically non-existent. However, when several team members left, there was, of course, a transfer of knowledge, but it was short and insufficient.
Lacking a clear understanding of the software architecture and the infrastructure, the new team then encountered numerous difficulties in modifying the source code. Although the application was deemed to have been sufficiently tested, it turned out that some unit tests failed but did not block the release, and automated functional tests were mostly disabled. Obvious consequence: significant difficulty in getting out releases because most of the changes had side effects on the application, introducing bugs or regressions. The actual content of the releases was unclear, the release notes being vague and often incomplete. And we can add to that the pressure of management, the working atmosphere and the deteriorating morale of the team which contributed to further reducing its ability to implement the functionalities.
So it was essential to establish a technical debt reduction project, which, notably, involved establishing new good practices. The key actions undertaken were:
- Automating the generation of architecture diagrams from markdown files in the git repository, making them easily accessible to developers.
- Generating test reports and displaying them in a dashboard, making them visible.
- Implementing a template for commit messages and automatically generating release notes making it possible to check what is delivered.
- Drafting a coding convention and implementing static analysis to ensure that these rules are respected and automatically producing a code quality analysis report.
Implementing these good practices allowed the team to re-deliver successfully, ultimately absorbing the technical debt. Above all, confidence and a favourable working climate were restored.
3. Documentation-as-Code or DaC
So we can speak of Documentation-as-code, DaC or even Doc-as-Code. But how can we define DaC? Through practices that apply coding techniques to writing documentation:
- Git
- Code/markdown
- Reviews
- Tests
- Follow-up on issues
Taken together, these practices provide a reliable definition of documentation. But it can also exist in several forms:
- User Stories: this is documentation.
- Source code: this is documentation if it is correctly named and follows the coding standards.
- Source code testing: Source code unit testing is documentation… if the tests are explained, and their limits are specified.
- Test plan and test results: this is also documentation.
- BDD: Gherkin files (.feature) are living documentation.
- X -as-Code (including Configuration-as-Code, Infra-as-Code, Security-as-Code…): this is also living documentation. Here are some examples: Ansible playbooks, Terraform tf files…
- Configuration files, if they are user-readable.
In this form, Documentation-as-Code has several major advantages:
- Genuinely useful documentation is kept up to date while requiring minimal work.
- Documentation is brought in earlier, in the same way as testing (we speak of “shift-left”).
- Knowledge is shared.
4. DaC: Four characteristics and four practices
We can recognise four essential characteristics of Documentation-as-Code:
- Objective: Each piece of documentation must have a purpose.
- Simplicity: the documentation must be kept simple.
- Stability: the documentation must be stable; it should not be created either too early or too late.
- Executable: Documentation should be executable when possible, based on tests.
In parallel with these four characteristics, we can also identify four practical applications of Documentation-as-Code:
- Create living (or executable) documentation as early as possible.
- Document the “why” and not the “how”.
- Update the documentation when the code is updated.
- Make the documentation visible.
Focus on documentation tools
A variety of automation tools can be used to produce the documentation. Here are some open source examples:
- Doxygen: produces documentation from annotations in the source code, stored in Git.
- PlantUML: produces graphics from text files, stored in Git.
- AsciiDoctor: produces PDF or HTML files from markdown files, stored in Git.
- PicklesDoc: produces a PDF or HTML file from BDD .features files, etc.
- JUnit Viewer and Allure: these produce test documentation (test reports).
- SonarQube: produces documentation on static analysis (e.g. analysis reports).
As you can see, the list is practically endless.
5. In conclusion…
As we have just seen in this article, much of the documentation is already available: all you need to do is find and centralise it. For the rest, it is possible to simplify documentation generation and automate its production: this is the example I gave with the software company in a highly regulated field. While the weight of documentation tasks became overwhelming and demotivated the team, automating specific documentation made it possible to reorganise work, improve team morale and, finally, simplify documentation work: a significant gain in time and efficiency!
