Why should you document your software architecture?
In this post, you'll learn why you should write and maintain software architecture documentation. I try to answer the question, which goals you pursue with the documentation of your software architecture and illuminate it from an economic point of view.
What can you expect from this post?
In this post, you'll learn why you should write and maintain software architecture documentation. I try to answer the question, which goals you pursue with the documentation of your software architecture and illuminate it from an economic point of view.
Table of Contents
Recently in a retrospective
Let me start with an illustration of a common and personally experienced way of thinking about software architecture documentation in agile teams.
An often expressed opinion about the documentation of software architecture 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 outt:
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.
Patrick Roos
Goals of software architecture documentation
Documenting software architecture isn't an end in itself, of course.
There are three goals that your software architecture documentation should fulfil.
📌 Software Architecture documentation creates a common understanding
As we can see in the figure above, the software architecture documentation should at least support the development team, e.g. when a new team member starts.
If we take this onboarding example, a new team member has a lot of questions:
- Where can I find an overview of the building blocks of the system?
- Why are you using Angular and not React? Why are you using Hibernate and not jOOQ?
- Where and how is the system deployed?
- fAre there any conventions I need to be aware of?
This brings us to the first goal of software architecture documentation:
Create a common understanding about the solution behind the system for different 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:
Create a common understanding to evaluate the software architecture from the different 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 this mean?
As a software architect, you've to transform 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
Support team work
Software architecture is a team effort, so it's most important that the software architecture documentation supports your team effort.
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 traceable architecture decisions. Nothing is more annoying than not knowing why you decided the way you did.
Support communication with 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-friendly views of the software architecture.
📌 Software architecture documentation guides the development team in implementing new product features
Software architecture documentation helps the entire development team implement the solution.
- What constraints do I need to consider?
- What non-functional requirements do I need to test?
- Which cross-cutting concepts do I need to follow?
- Are there architectural decisions I need to consider when implementing a particular feature?
An economical point of view about software architecture documentation
There's probably a simple mathematical formula that helps us look at this question from an economic point of view (kudos to Nikolai Ashanin with his blog post on software architecture documentation):
(Cx - Cy) > Cdiff
Cx = The cost of the product development without technical documentation per year,
Cy = The cost of the product development with the technical documentation per year,
Cdiff = The cost of maintaining technical documentation per year
This formula helps from an economic point of view, what documentation you need to create and how often it needs to be updated.
Comments ()