Document Your Agile Architecture

2024-07-01

Tools

Here is a set of tools to explain and document your architecture, design, and source code. The tools should support the developers in their daily work activities. They should simplify their working.

Asciidoc: is the standard for writing technical documentation ^[1]. All modern DevOps platforms such GitHub, GitLab, Bitbucket support this approach. Static websites written with Asciidoc or Markdown are the current good approach for digital product technical documentation. The documents can be put into a source code management system and be versioned.
plantUML: You can draw all UML artifacts with plantUML. Extensions are available for drawing C4 Model diagrams.

You will hit a wall if you draw a lot of views from the same model using plantUML. The father of C4 Model developed the semantic model [7] of Structurizr to diminish effort and avoid errors.

Start small. Use plantUML to document your initial architecture. You can later if needed migrate to Structurizr.
Mermaid: Mermaid provides a set of diagram types I find useful for documenting software architecture.
API Documentation: Legible and maintainable source code should be well-documented.
JavaDoc is the perfect tool for Java projects. Starting with JDK 23, Javadoc supports Markdown as a markup language to simplify the documentation process.
Doxygen is a similar approach for a wide range of programming languages. It is the de-facto standard documentation tool for C++ and C applications.

We recommend using the documentation tool provided with your technological stack.
TDD And BDD: Automatic unit and integration tests provide traceability between requirements and source code artifacts ^[2]. Well-documented approaches such as fitness functions [6] extend the approach to non-functional specifications.

You can add traceability information as annotations to your tests. The dependency between requirements, tests, and test campaigns can be automatically documented. The traceability reports fulfill the expectations of certification authorities such as FDA, FAA, and TÜV.

A huge variety of diagram types are available through Kroki if your product has special documentation constraints. The tooling is well-integrated with the Asciidoc toolchain.

Static Website

A software architecture and design documentation [5] solution shall fulfill the following constraints:

The documentation and the source code are synchronized and versioned. They are stored in a git repository and tagged accordingly.
The documentation is generated and published without manual activities. A simple script generates the whole documentation and makes it available to all interested parties.
Diagrams and sketches are integrated in the documentation. You do not need to generate or manually copy diagrams into the documentation. A proven approach is text-based diagramming tools.
The documentation is searchable.
API and source code documentation are linked to the documentation. Artifacts created with OpenAPI, JavaDoc, or Doxygen shall be part of the integrated documentation portfolio.

Technical digital product documentation creation embraces the docs-as-code philosophy. Similar to our source code practices, product documentation has been version controlled, subjected to the same gatekeeping systems, and auto-delivered by using the same CI/CD pipeline.

This has allowed us to maintain a high level of quality and consistency across our documentation, while also enabling our engineers to contribute to the documentation in the same way they contribute to the codebase.

The actual good solution is to use a static website generator [3] [2] [4].

Wiki approaches are usable if their content is stored in a repository as textual artifacts. They must support searching, diagramming, and cross-referencing.

We are using Hugo as a static web generator. The documentation theme is Docsy. The authors of the theme are collaborators of Google and invest time and effort in the theme.

We are using Asciidoc as documentation markup language. The features are equivalent to DocBook markup language. Extensive diagramming options are provided. An alternative integrated approach is the generation of diagrams with Kroki.

AsciiDoc supports source code highlighters to publish nice looking and legible code snippets.

We use plantUML and Mermaid for creating diagrams.

The site is stored in a Git repository. The generation and publishing of the whole site use a simple script.

arc42 Template

I regularly use the arc42 template to mitigate lengthy discussions about how extensive software architecture shall be documented. The founders of iSAQB certification institute created the arc42 template. They actively maintain and enhance the template and associated documentation.

The template emphasizes the use of UML and C4 Model notations for diagrams. plantUML supports all the required diagram types.

It answers the following two questions in a pragmatic way, but can be tailored to your specific needs:

What should we document and communicate about our architecture?
How should we document and communicate it?

arc42 is a pretty minimalistic documentation template compared to other templates ^[3].

1 - Introduction and Goals: A short description of the requirements, a few quality goals, and a listing of important stakeholders.
2 - Constraints: Anything that constrains teams in design and implementation decisions or decisions about related processes. Are valid for whole organizations and companies.
3 - Context and Scope: Separate your system from its external systems and users. Specify the external interfaces shown either in a business or technical perspective.
4 - Solution Strategy: Summary of the fundamental decisions and solution strategies that shape the architecture. It can include technology, top-level decomposition, approaches to achieve top quality goals, and relevant organizational decisions.
5 - Building Block View: A static decomposition of the system, shown as a hierarchy of white boxes up to the right level of abstraction.
6 - Runtime View: Behavior of building blocks as scenarios, covering use cases, operation, administration, error handling, and features. An example of this might be a sequence diagram.
7 - Deployment View: The technical infrastructure with environments, servers, and topologies. Mapping of building Blocks to the right infrastructure.
8 - Crosscutting Concepts: Principal regulations and solution approaches are relevant in multiple parts of the system. The opportunity between different software components.
9 - Architectural Decisions: Important, expensive, critical, large scale, or risky architecture decisions including rationales.
10 - Quality Requirements: Quality requirements as scenarios. The requirements shall define a quality tree and associated measurements. The quality goals can be taken from Introduction and goals.
Use a fitness function-based approach.
11 - Risks and Technical Debt: The known technical risks or already present technical debt.
What potential problems exist in the application itself or its surroundings?
What does the development team fear for the future?
12 - Glossary: Important domain and technical terms that stakeholders use when discussing the system.
Try to write all documents in English.

No matter how big your Project is, arc42 approach keeps the documentation relatively slim and maintainable.

Use this fact to challenge your organization. You have found a valid and well-documented architecture documentation approach and template. Either your team can use it, or your organization shall provide a better alternative with similar recognition and support level.

Technical writers are very satisfied with Asciidoc and the provided template.

Lessons Learnt

You must provide documentation to empower new team members and technical users of your components [2]. Collaborators and developers will read the documentation to understand the architecture and design decisions before they start using or changing the code.

Be honest. No other person will read the documentation ^[4]. Cherish the documentation as a living artifact. Discuss the content with your team members and improve it continuously.

Collaborators should have a working understanding of UML [3].

The documentation shall be written in English. Not all current and future team members are fluent with the local language.

As soon as your product is successful, you will work with international teams and nearshore development centers. The sole commonly spoken and written language will be English.

You shall document architectural design decisions ADR. These records document the evolution of your digital solution over the years.

Study the documentation of successful open-source projects. They provide good examples of how to document your digital product.

Most developers do not study the source code before using an open-source library or a component. They do not have direct access to the developers of the library or component. They rely on the documentation to understand the usage and the design decisions.

Code examples are highly valued in the documentation.

Most organizations are documentation crazy. Old school managers cannot handle the agile manifesto rule. The simplest approach to tame them is to use an agile friendly approach such as arc42.

Too many companies believe that wikis and sharepoint sites are a good approach. Forget about it. Sharepoint is still not supporting searching in documents. You must hire a team to configure and extend Confluence to have a usable documentation platform.

Please never use Microsoft Word and Excel for technical documentation. This will never work.

References

[1] N. Ford, R. Parsons, and P. Kua, Building Evolutionary Architectures: Automated Software Governance, Second. O’Reilly Media, 2023 [Online]. Available: https://www.amazon.com/dp/B0BN4T1P27

[2] P. Clements, Documenting software architectures views and beyond. Addison-Wesley, 2011 [Online]. Available: https://www.amazon.com/dp/0321552687

[3] M. Fowler, UML Distilled, Third. Addison-Wesley Professional, 2003 [Online]. Available: https://www.amazon.com/dp/B07H4WN84Z

1. Asciidoc is semantically equivalent to DocBook. This markup standard is used to write all technical books published by O’Reilly.

2. Google developed and maintains unit test libraries for C and CC++.

3. It is probably the main reason why arc42 is still used and the other templates are fading away.

4. The exception is if your digital product requires a certification such as functional safety or FDA approval.