Architecture documentation authoring and dissemination
This article will present how I envisage software documentation from the development, and tooling side. First of all, architecture documentation is a critical asset as soon as you are more than two or three in the team. As Nikolay described in his article, the primary goals are knowledge sharing, communication, and analyses. But documenting the system’s architecture is a difficult task. You always face the divergence between code and the documentation. Word/pdf documents or modelization files contain the documentation, making it challenging to find information and navigate between the artifacts.
For sure we can argue that each tool addresses different stakeholder needs. A modeling tool might be the preferred tool for a software architect, the repository selected by a developer, and a pdf for a management level. But we have to be honest; maintaining all is a pain. While setting up the documentation with my team, I asked the group: “what do we/they “feel” about the architecture and the documentation? It came out that:
- Architecture is mostly from developers for developers
- Architecture is living; it changes iterations after iterations
- Code and architecture always diverge over time
- Architecture is not a book you read from page one to the end
- Architecture is not something to fulfill a process step, but it needs a process
Based on those thoughts, the concept of content as code was quite promising. Indeed the same rules should apply for the documentation as for the code. If the architecture is from developers for developers, why not use the same tool landscape (e.g., Git, vscode, or any IDE). Architecture is a living object like code, and it is also a critical asset we can apply the same processes (e.g., Quality gates within a CI, Merge Request…). Architecture and code always diverge over time; maybe putting them together might reduce the risk. We ended with a classical developer tool landscape for the authoring part: Gitlab or any other source control system, markdown for the content, and Git for versioning.
With that solution, we were able to guarantee:
- The versioning: the documentation evolves like the code following the same life cycle.
- The quality, with merge requests like code
- The traceability: with the ability to compare different versions as we are text-based.
The authoring aspect is addressed, but the reader’s side was still not implemented. The team mentioned that you do not read architecture documentation like a book, starting from page one to the end. We prefer to navigate from a piece of information to another, from a high level of abstraction to an implementation detail. Fundamentally the reader wants to navigate! Which system has in his heart the navigability? The Web indeed! The documentation should be web-based. The web is navigable, links are the heart of the web, and with a single URL, you can dive into your documentation.
As depicted in the previous picture, we extended our tool landscape to generate a static website with Jekyll and the full integration into our CI/CD pipeline. Now the generated website is a kind of artifact like any dll or cloud deployment. It is synchronized with the code. It is readable to anyone who has the URL, and the unique tool needed by a reader is a web browser.
To conclude, in this article I presented how I tried with my team to address the authoring and dissemination of software architecture. Below some links to tools or concepts I used. In the next article, I will present how we handled the architecture diagrams.
