The Ultimate Guide To Software Architecture Documentation

This guide shows you how to write, structure, visualize and manage software architecture documentation in a lean way using appropriate documentation tools.

The Ultimate Guide To Software Architecture Documentation
The C4 model and the arc42 template will help you write a good software architecture documentation. This guide shows you how.

Table of Contents

Why should we document software architecture?

An often expressed opinion about software architecture documentation in "agile" teams is:

The code documents the system. We don't need any further documentation.

But this statement is only half the truth. There are several questions that remain unanswered in the code.

  • What are the goals of the system?
  • What are the non-functional requirements?
  • What are the architectural decisions and their arguments?
  • ...

As Simon Brown has correctly pointed out:

The code doesn't tell the whole story.

Long story short: You should document the software architecture of your system. Take a look at the goals you should fulfil with your documentation, and you'll understand why.

Technical Debt Scenario #5: The code documents the system.
Unfortunately, several long-time developers have left the product team. In addition, there is virtually no technical documentation for the system. Even the architectural decisions are no longer traceable. What would you do to eliminate this kind of technical debt?
Blog Post: Technical debt due to lack of documentation

Goals of software architecture documentation

There are three goals that your software architecture documentation should fulfil.

Software architecture documentation creates a common understanding

Software architecture documentation should at least support the development team, for example, when a new team member starts.

Let's take the onboarding example, a new team member has a lot of questions:

  • Where can I find an overview of the system's building blocks?
  • Why are you using Angular and not React? Why are you using Hibernate and not jOOQ?
  • Where and how is the system deployed?
  • Are there any conventions I need to be aware of?

This brings us to the first goal of software architecture documentation:

Software architecture documentation creates a common understanding of the solution behind the system for various stakeholders

There are usually many different stakeholders interested in different aspects of our system: Software Architects, Software Engineers, Ops, Support, Testing, POs, Project Managers, SMEs, Business Sponsors and so on.

You can create different views of your system's architecture by developing a common understanding of your system's software architecture.

With this understanding, the various stakeholders can evaluate the underlying software architecture from their perspective.

In this way, we can concretize the goal described above with the evaluation part:

The documentation makes it possible to evaluate the software architecture from the perspective of the various stakeholders

Software architecture documentation allows your stakeholders to judge whether the system is achieving the goal, since they often can't dive into the code.

With good architecture documentation, they can answer the following questions:

  • Does the chosen architecture fit the solution?
  • Is the architecture appropriate?

In this way, architectural documentation often prevents other goals, constraints, and non-functional requirements from creeping in.

Let me give a practical example here.

I've often heard from various stakeholders: "The system must be fast."

But what does that mean?

As a software architect, you have to turn these expectations into concrete quality goals, i.e., non-functional requirements with supporting quality scenarios. You record these quality goals in the architecture documentation, which in turn helps your team to implement the solution with the agreed non-functional requirements.

Software architecture documentation supports architectural work

Software architecture documentation supports team work

Software architecture is a team effort, so it's most important that the software architecture documentation supports your team effort.

Do we need a software architect in our agile team?
This question often comes up in agile teams. In this blog post, we look for the answer to this question in the context of the various agile and organisational frameworks like Scrum, LeSS, SAFe, Disciplined Agile and draw a conclusion.
See also this article about the role of the software architect

As a team member, it's important to actively know (and pass on to new team members) the goals, constraints, and non-functional requirements within the team. This information is often very important in team architecture workshops.

It's important to make understandable and comprehensible architecture decisions. Nothing is more annoying than not knowing why you decided the way you did.

Software architecture documentation guides the development team in implementing new product features

Documenting software architecture helps the entire development team implement the solution.

  • What constraints do I need to consider?
  • Which non-functional requirements do I need to test?
  • Which overarching concepts do I need to follow?
  • Are there architectural decisions I need to consider when implementing a particular feature?

Software architecture documentation supports the communication with external stakeholders

A large part of software architecture work is communication. In particular, communication with stakeholders is key to effective and focused discussion outcomes.

Good software architecture documentation supports communication with external stakeholders. It contains different and stakeholder-appropriate views of the software architecture.

How should we structure software architecture documentation?

An proven approach to structuring software architecture documentation is the arc42 template.

arc42 Logo (Source)

What is the arc42 template?

  • arc42 provides a template for documenting and communicating software
    and system architectures.
  • arc42 is based on practical experience of many systems in various domains,
    from information and web systems, real-time and embedded to business
    intelligence and data warehouses.
  • arc42 supports arbitrary technologies and tools.
  • arc42 is completely process independent and is particularly well suited for lean and agile development approaches.
  • arc42 is open source and can be used free of charge in both the commercial and private sectors.
  • arc42 is available in several languages.
  • arc42 is available in different formats like .adoc, .docx, .rst, .md, .tex, ...
GitHub - arc42/arc42-template: arc42 - the template for software architecture documentation and communication
arc42 - the template for software architecture documentation and communication - GitHub - arc42/arc42-template: arc42 - the template for software architecture documentation and communication
GitHub Repository of the arc42 Template

How is the Software Architecture according to the arc42 template structured?

The following figure shows the resulting structure of the arc42 template.

The structure of the arc42 template (Source)

Good examples of an arc42 documentation

Are there any possible pitfalls in the handling with arc42?

Upfront document everything

Don't document everything in advance. Think of the arc42 template as a cabinet for documentation. You put something on a shelf as you work on it. This is how software architecture documentation emerges, evolves, and stays
current.

Don't includes Tutorials or Q&A sections

The most important thing in arc42 is the structure. The structure doesn’t
provide a space for guides or Q&A sections.

Don't put any specific things like customer names or similar

Don't write customer-specific things in the software architecture documentation, unless your building blocks are structured in a customer-oriented way.

Alternative documentation and structuring approaches

There are some alternative structuring and documentation approaches.

How should we visualize the software architecture?

The C4 model is a good approach to obtain a common set of abstractions. It's an abstraction-first approach and is notation independent.

The C4 model looks at the static structures of a software system in terms of containers, components and code. And people use the software systems we build.

Abstractions of the C4 Model (Source)

What is a software system in C4?
A software system is the highest level of abstraction and describes
something that adds value to its users, whether they are human
or not.

What is a Container in C4?
A container (not Docker!) is a separately deployable / executable thing.

What is Component in C4?
A component is a grouping of related functionality encapsulated
behind a well-defined interface. If you're using a language like Java or C#, the easiest way to think of a component is that it's a collection of implementation classes behind an interface.

What are the core views of C4?

With these abstractions, we can create a context view (Level 1), a container view (Level 2), a component view (Level 3) and a code view (Level 4).

The four levels of the C4 Model. Each level has a different target audience (Source)

Level 1: System Context Diagram

The following illustration shows the system which is embedded in its context.

A system context diagram (Source)

Level 2: Container Diagram

If we zoom into the system (the internet banking system in the figure above), we get the container view of this system.

Each of these containers is separately deployable.

A container diagram (Source)

Level 3: Component Diagram

If we want to take a look inside a specific container, like the API application, we get the component view of that container.

A component diagram (Source)

Level 4: Code

If we go deep into a particular component, we arrive at a "code" view.

Level 4: Code Diagram (Source)

This can be a class diagram. But you can often generate this kind of view by an idea, if necessary.

UML class diagrams | IntelliJ IDEA

Is the C4 model compatible with arc42?

Yes, arc42 and C4 can be used complementarily.

The C4 diagrams are relevant in the following arc42 chapters:

Besides the C4 diagrams presented above, there are some additional diagrams of C4 that can be inserted into arc42.

How do we write and manage software architecture documentation?

As with any software, there are requirements for technical documentation. Gernot Starke has excellently documented these requirements in the following blog post:

Principles of technical documentation
This article collects fundamental requirements for technicaldocumentation, especially software architecture documentation, togetherwith ideas how to *satisfy* those.

A summary of the documentation requirements can be seen in the following figure from the blog post above:

All documentation requirements (Source)

Meeting some of these requirements (e.g., req-7, req-9, req-10, and req-11) leads to the conclusion that we should treat the document as code "Documentation as Code" or "Docs-as-Code".

What is "Documentation as Code" ?

"Documentation as Code" means that your documentation process benefits from the same practices you use to develop successful software.

Some of these practices are:

  • Storing content in a version control system
  • Separation of content, configuration, and presentation
  • Use of automation for compilation, validation, verification and publishing (CI/CD)
  • Reuse shared materials (DRY)
  • ...and use your IDE to write content ;-)

With this technique we get some value out-of-the-box:

  • Structuring of the whole document into subdocuments
  • Restructuring of the documentation according to specific stakeholder
  • Reference images, not embedding
  • Simple versioning "handle documentation as code”
  • Format of the documentation content like source code
  • Documentation Reviews, pull requests, versioning through Git tooling
  • Conversion to various presentation formats like HTML5, PDF, DocBook, Confluence, ...
Treat documentation like code in a common development workflow

In Documentation as Code we can distinguish the following process steps: Authoring (write, validate and preview the documentation content), Converting (documents to the pulication formats like HTML, DocBook, PDF, etc.), and Publishing (Build and deploy documentation artefacts). For each of these steps there are some tools that I can recommend to fulfil the process step.

Authoring: AsciiDoc

AsciiDoc is a plain text markup language for writing technical content. Use the AsciiDoc format to write your content.

AsciiDoc Logo

Convert: Asciidoctor

Asciidoctor is a fast processor for parsing AsciiDoc® into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.

Asciidoctor Logo

Publish: Maven, Gradle, docToolChain

docToolchain is a collection of scripts that makes it easy to create and maintain powerful technical documentation. Built on best-of-breed open source technologies, we deliver the best docs toolchain so you don’t have to.

Available tasks of the docToolchain (Source)

And what's about diagrams?

Like documentation, you can treat diagrams like code.

Diagrams as Code 1.0

A classical approach to describe diagrams in text can be done with PlantUML, Mermaid or GraphViz.

Describe a diagram with text in PlantUML

These diagrams can be embedded directly into AsciiDoc content and converted with AsciiDoctor.

[plantuml, target=diagram-classes, format=png]   
....
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
....
PlantUML Code in AsciiDoc embedded

Now let's combine diagrams as code and the C4 model. This brings us to Diagrams as Code 2.0.

Diagrams as Code 2.0

What if we could describe our C4 model in text form and generate the C4 diagrams directly?
This is where Structurizr comes in. It brings diagrams as code into a new dimension - Diagrams as Code 2.0.

Structurizr Logo

With the Structurizr DSL we can describe the Software with the C4 abstractions.

Structurizr DSL Example (Source)

After describing the C4 model of our software system, we can create all defined views directly (with different representations).

Awesome, isn't it?

By the way: Simon Browns gave a great talk about diagrams as code 2.0 with Structurizr.

Combine everything together

Now you have the whole toolbox for software architecture documentation:

Combine everything together and get a powerful software architecture documentation

I've created an example repository where I've brought all these techniques and technologies together. Check it out.

GitHub - bitsmuggler/arc42-c4-software-architecture-documentation-example: This example shows how you can use arc42 in combination with the C4 model and the Documentation as Code technique.
This example shows how you can use arc42 in combination with the C4 model and the Documentation as Code technique. - GitHub - bitsmuggler/arc42-c4-software-architecture-documentation-example: This ...

Further supporting software architecture documentation tools

All Documentation as Code Tools can be found under the following link 👇

Documentation as Code Tools
This page contains all the modern tools, languages and frameworks, platforms and techniques you need to know to treat documentation like code.