When working in Parser, a common pain point we see across companies is the lack of effective architecture documentation. Architecture documentation is essential because it helps in planning and managing projects, and defines a clear understanding of the entire software system of the company. It’s also very useful when onboarding new employees.

This gap is even more obvious when working with start-ups or companies that grew fast. When asking for architecture documentation, you get directed to incomplete diagrams, outdated documents made by unreachable people, or code-level documentation that usually does not help you to understand the big picture. You can also get delighted by a colourful emergency exit kind of map if a drawing board is close:

In case of fire please go to “Bus logic”

To fulfil this gap, companies need to dedicate time and effort to document their software systems, and arc42 is here to help.

What is arc42?

Arc42 defines itself as:

All you ever need to construct, communicate and document your software architecture. Proven, practical and pragmatic. Free and open source, takes the pain out of documentation.

And that’s what it is!

Arc42 is a template for architecture communication and documentation, technology agnostic. It is divided into 12 sections, each one addressing a different software aspect. These sections are divided into subsections and every one of them is optional, so it’s up to you to decide if you want to include them in your documentation or not.

Pretty complete, isn’t it?

1. Introduction and Goals

Brief introduction of the purpose of the document. Include here the requirements, quality goals and a table with the main stakeholders.

2. Constraints

Add here any constraint in terms of design or implementation. This can go beyond individual systems and for whole organisations and companies.

3. Context and Scope

Context delimits your system from its external communication partners and documents its external interfaces. You should reflect it from a business or domain perspective (always) and a technical perspective (optional).

4. Solution Strategy

Include a short summary and explanation of the fundamental decisions and solution strategies that shape the system’s architecture. These can be technology or organisational decisions, architecture patterns, or decisions on how to achieve key quality goals.

5. Building Block View

Shows the static decomposition of the system into building blocks (modules, components, subsystems…) as well as their dependencies (relationships, associations…).

You can add as many levels as you require, but usually one or two are enough to give a good understanding to your stakeholders.

6. Runtime View

Behaviour of building blocks as scenarios, covering important use cases or features, interactions at critical external interfaces, operation and administration and error scenarios. UML sequence diagrams are probably the best  way of showing the runtime behaviour of your components.

7. Deployment

Software does not run without hardware. This underlying infrastructure can and will influence your system and/or some cross-cutting concepts. Document here the technical infrastructure used to execute your system and the mapping of building blocks to that infrastructure.

8. Crosscutting Concepts

This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (i.e. cross-cutting) of your system. Such concepts are often related to multiple building blocks.

Logging and security are usually present in every crosscutting concepts section. Monitoring, performance or exception handling are also good examples.

9. Architectural Decisions

Include here every important, expensive, critical, large scale or risky architecture decisions and their rationales. The best way to do it is using Architecture Decision Records (ADRs).

10. Quality Requirements

Quality requirements as scenarios, with a quality tree to provide high-level overview. These requirements should be linked with the quality goals described in section 1.

11. Risks and Technical Debt

A prioritised list of risks and/or technical debts, probably including suggested measures to minimise, mitigate or avoid risks, or reduce technical debts.

12. Glossary

The most important domain and technical terms that your stakeholders use when discussing the system. A simple table with columns <Term> and <Definition> is recommended.

Resources

Arc42 offers different resources to help you with the task of fulfilling your document:

• Documentation: A super complete documentation site, including good explanations for every section above, 144 useful tips and more.
• Templates: Best way to kick-off. They are not limited to document format, you can also find markdown, html, latex or even confluence formats as well.
• Real world examples: Architecture of real systems, documented with the arc42 template. This helps you jumpstart your own documentation.

An honest opinion

I’ve used the arc42 framework different times during my career. It was the tool of choice in one of my previous experiences and I later decided to use it as the outcome of a couple of architecture assessments for different companies, with very good results. 

I find it really useful and easy to follow. The templates and real world examples linked in their website are really helpful, and good to get inspiration from. I also find it really important to decide which sections and subsections you want to include, as if you go for all of them it can get really long to complete, and you may find some content duplication if your project is not too big or complex.

I strongly recommend giving it a try, it’s very easy, just download any of the templates, and start documenting!