The Ultimate Guide To Software Architecture Documentation
Table of Contents
- Why should we document software architecture?
- How should we structure software architecture documentation?
- How should we visualize software architecture?
- How do we write and manage software architecture documentation?
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?
- ...
Tip: Take a look at the Software Architecture Canvas to get answers to these questions in a collaborative way.
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.
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.
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.
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 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.
Good examples of an arc42 documentation
- HTML Sanity Checker (HtmlSC) Architecture Documentation (Gernot Starke)
HTML Sanity Checker (HtmlSC) shall support authors creating digital formats
with hyperlinks and integration of images and similar resources. - DokChess (Stefan Zörner)
DokChess is a fully functional chess engine. - Gradle as an example for arc42 (Stefan Zörner) 🇩🇪
Gradle automates the building, testing and delivery of software.
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.
- Recommended Practice for Architectural Description of Software-Intensive Systems (IEEE 1417)
- Documenting Software Architecture (SEI)
- Software Architecture for Developers (Simon Brown)
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.
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).
Level 1: System Context Diagram
The following illustration shows the system which is embedded in its context.
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.
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.
Level 4: Code
If we go deep into a particular component, we arrive at a "code" view.
This can be a class diagram. But you can often generate this kind of view by an idea, if necessary.
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:
- C4 System Context diagram can be placed in arc42 chapter 3 "Context and Scope"
- C4 Container Diagram can be placed in arc42 Chapter 5 Building Block View (Level 1)
- C4 Component Diagram can be placed in arc42 Chapter 5 Building Block View (Level 2)
- Code Diagram can be placed in arc42 Chapter 5 Building Block View (Level 3)
Besides the C4 diagrams presented above, there are some additional diagrams of C4 that can be inserted into arc42.
- C4 Dynamic Diagram can be placed into arc42 Chapter 6 Runtime View
- C4 Deployment Diagram can be placed into arc42 Chapter 7 Deployment View
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:
A summary of the documentation requirements can be seen in the following figure from the blog post above:
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, ...
Like Code by Anne Gentle
Are there any recommended tools for Documentation as Code?
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.
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.
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.
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.
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.
With the Structurizr DSL we can describe the Software with the C4 abstractions.
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:
- Structure it with arc42
- Describe and visualize it with the C4 model
- Treat your documentation and diagrams like code with AsciiDoc, AsciiDoctor, docToolChain and Structurizr
- ...and integrate it into your development workflow.
I've created an example repository where I've brought all these techniques and technologies together. Check it out.
Further supporting software architecture documentation tools
All Documentation as Code Tools can be found under the following link 👇
Recommended Software Architecture Documentation Books
- Software-Architekturen dokumentieren und kommunizieren (German) von Stefan Zörner
- arc42 by Example by Gernot Starke and Ralf D. Müller
- arc42 in Aktion (German) by Gernot Starke and Peter Hrschuka
- Software Architecture for devlopers by Simon Brown
- The C4 model for visualizing software architecture by Simon Brown
- Docs Like Code by Anne Gentle