DEV Community


Posted on

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.


Top comments (1)

outsourcedev profile image

Interesting article, I think a key thing to establish up front is if the reason is
forward engineering - ie design then coding
reverse engineering - from code back to a deduced design
maintenance - where the key tracking artefact is a ticket (from customer report through to the engineers change control ticket)
a combination of all of them (the ultimate goal for Living documentation)

As they have different motivations and goals. Capturing design decisions in ADRs is step 1 but how to get them relevant to the code?
Add a text reference to the ADR file or ticket number?
Add a hyperlink as a comment in the source?
Make the ADR a sidecar file?
Convert ADR into Text and include in the code, via a well placed tag?

More detailed explanation of Living documentation at