Software architecture documentation - Made easy with arc42 and C4

Good software architecture documentation is really important to successfully manage projects, because it helps:

• aligning everybody’s understanding of the entire software system
• developing and maintaining software fast and efficiently
• on-boarding new employees into the project in a short time
• planning your project and resources
• monitoring your risks

But even though good software architecture documentation provides undoubtedly essential benefits it is also an rather unpopular task.

But why is that?

Reasons for lacking architecture documentation are manifold

Usually a project is short of resources and budget and especially in the beginning it is not staffed with technical writers. The documentation task is then delegated to developers, but their skills in writing comprehensible documentation are often falling short.

Also an often heard argument from developers is: "I am writing clean code. The code is the documentation."

Really? Well, clean code is surely an very important principle in software engineering. It helps you developing stable, understandable and easier to test and maintain software units. It is definitely a valuable contribution to improve the software quality.

But if you are getting on-boarded to a new project: Does clean code alone help you understanding the big picture? Does it tell you something regarding design decisions, critical dynamic sequences, control and data flow and how the entire systems is tailored into building-blocks? Probably not. So clean code is not a replacement for architecture documentation, it is a strong addition to it.

Another reason people are reluctant in writing documentation is, because their contributed content is often closely related with the tools they are using. They need to spend significant time with understanding the capabilities and hidden features of a certain UML Tool. And then in the middle of the project purchasing decides to switch from Tool X to Tool Y …

And finally it is often unclear, what should be documented and how it should be done. What is important and what can be left out? What is the right level of abstraction and how to visual the structural relationships of your software system?

Be as pragmatic as possible, but as formal as necessary

So, how can we then convince people spending more time in documenting their architecture? And how can we make it more efficient and less expensive and maybe even more exciting?

We have made good experience in equipping them with a doc-as-code approach, that is as pragmatic as possible, i.e.:

• using a guideline, that is telling you what and how to document
• concentrating on the most important aspects, but then be precise and complete
• not wasting time with heavyweight GUI tools

but nevertheless be as formal as necessary, i.e.:

• agree on a notation and abstraction, that everybody understands
• minimize the room for interpretation
• be concise and consistent

Precisely we suggest to leverage the capabilities of two methodologies, which in combination fulfill those requirements:

• arc42, which is a template for software architecture communication and documentation
• the C4 model, which is an "abstraction-first" approach to diagramming software architecture

Arc42

As stated on the website arc42 is a template for architecture communication and documentation. It is tailored into 12 separate chapters, each addressing a certain software architecture aspect.

But it is not only a collection of headlines. Each aspect is equipped with additional information, regarding:

• Content → What should be documented?
• Motivation → Why should it be documented?
• Form → How should it be documented?

Furthermore there are many examples and practical tips. Check their corresponding pages for detailed information of each chapter.

When you get more into the details you will see that there are at least four chapters, that deal with the visual representation of certain architectural aspects:

• Context and Scope, for visualizing the scope of the system and its external interfaces
• Building Block View, for showing the static decomposition of the system
• Run-time View, for illustrating the most important interactions between your build blocks
• Deployment View, for explaining how building-blocks are deployed to technical infrastructure

This is where the C4 model is joining the game as a useful supplement.

C4 Model

Whereas arc42 is meant to be a complete guideline covering all documentation aspects, the focus of the C4 model is an "abstraction-first" approach to diagramming software architecture.

The C4 model is intended to be an pragmatic and lightweight alternative to other software architecture modeling tools like UML, SysML or ArchiMate. It provides a framework to visualize the static structure of the software architecture in a top-down approach, but with only a small set of meta-data and diagram types.

It comes with a set of abstractions, namely software systems, containers, components and persons. Those can be set in relation to each other in different core diagrams, which are meant to be used for visualizing different aspects:

• context diagram, for showing the architecture’s "big picture"
• container diagram, for zooming into major building-blocks
• component diagram, for decomposing building blocks into smaller entities

This is the place where you can complete the arc42 chapters with meaningful and expressive diagrams:

• C4 context diagrams in Arc42 chapter "Context and Scope"
• C4 container diagrams in Arc42 chapter "Building Block View (Level 1)"
• C4 component diagrams in Arc42 chapter "Building Block View (Level 2)"

There are also code diagrams for showing code dependencies with UML-like class elements. This is something I personally would not spend much time in:

1. Here you are already on a level of detail, where the content (i.e. code) is changing continuously. It is probably too much effort to maintain the documentation in parallel.
2. There are a lot of useful re-engineering tools around, that can automatically create diagrams from existing code. By the way: clean code will help a lot in that case. :)

Meanwhile the C4 model has evolved with supplementary diagrams for showing other aspects than just the static structure. Interesting in our case are the deployment diagrams and dynamic diagrams.

And again there is a nice mapping between arc42 and C4:

• C4 dynamic diagrams in Arc42 chapter "Run-time View"
• C4 deployment diagrams in Arc42 chapter "Deployment View"

Where I have to say, that I would prefer UML-like sequence diagrams for showing the dynamic behavior and flow logic between software components instead of C4 dynamic diagrams.

There is a lot of tooling available based upon the C4 model, e.g. extensions for Enterprise Architect, PlantUML or Microsoft Visio. Furthermore the meta-model is described and even a DSL is available, in case you want to build your own tools on top of it.

Conclusion

The two methodologies complement each other very well. You can use arc42 for the general documentation structure and C4 for visualizing the most important aspects and relations between your software components.

It is actually very easy to implement an applicable tool-chain upon it. A straightforward and lightweight setup could look like that:

• Setting-up a git repository, containing adoc (asciidoc) files, one for each arc42 chapter and a diagram folder, containing C4 diagrams as puml (plantuml) files
• Installing Visual Studio Code as Editor, together with plug-ins for asciidoc and plantuml
• Setting-up asciidoctor in CI/CD pipeline for automatic documentation generation, e.g. as PDF and/or HTML

Fortunately the arc42 template is already available in asciidoc format.

Having the documentation available in such a "code-like" manner gives you the opportunity to merge and diff between different versions.

And finally the entry barrier for a developer is much lower than using cumbersome UML tools.

But don't forget: This article is only about the selection of methods and tools, that helps you with your architecture documentation. At the end you need experienced architects and developers to achieve high quality content...

Feel free to contact me if you have further questions.