The lean and pragmatic approach to documenting software architecture
"OK, I've documented the existing system, clarified user requirements, figured out the best approach to system design, picked implementation algorithms, and patterns, designed the data model... I've finished software architecture; we are ready to GO!
Where is architecture documentation? Oh, some of the documents are on network share under the folder called "Project stuff." I also got few scribbles and napkin notes shoved in the upper cabinet drawer. And yeah, some whiteboard pictures are on my phone.
Why?"
Documenting Software Projects
A rare software engineer is excited about writing documentation for their latest project. Sometimes it's an afterthought, produced as a response to the angry crowd of technical writers, QA engineers, or end-users.
The same can be said about software architecture. Initial data gathering, brainstorming sessions, proposed models, security concepts - these activities generate a lot of notes that should, in theory, go into software architecture documentation.
But documenting software architecture in the age of agile development is a challenging concept. It balances between two extremes of “document absolutely everything” inherited from waterfall and “document nothing, real software developers just read code listing.”
The problem with the former is creating busywork that few people would care about, obsolete far before completion. The issue with the latter is lack of communication within the team, the potential for misunderstandings causing future rework, no recorded trail for crucial design decisions.
The solution is to change the approach to documentation and focus on creating a lean document of high value by documenting what’s important.
But how?
The easiest way is to follow the template.
You can use the C4 Model for Software Architecture by Simon Brown or Documenting Software Architecture by Paul Clement.
My personal preference for the lean documentation template is arc42. I was introduced to it while working at Bosch (not surprisingly since the authors are German), and to me, it feels the most natural way to record software architecture.
Over the years, I've presented arc42 concepts to a few teams, and the typical initial reaction was, "It looks nice but also very complicated."
It looks complicated, but it doesn't have to be. The template is a list of guideposts, helping you to organize the information most logically. It's not a crime to skip a section or change things around - documentation should be lean and pragmatic, as template creators had intended. Some projects may have a page or two of content, while others must include submodules also written in arc42.
Let's take a look at the top-level sections of the template (as of version 7).
arc42 sections
- Introduction and Goals
- Requirements Overview
- Quality Goals
- Stakeholders
- Constraints
- Context and scope
- Solution strategy
- Building Block View
- Runtime View
- Deployment View
- Concepts
- Architecture Decisions
- Quality
- Risks and technical debt
- Glossary
Too much? Let's investigate.
Introduction and Goals
In a few words, explain why this project exists and what problem it meant to solve. If this is version 2.0, it would be an excellent spot to link to 1.0 documentation.
Requirements Overview
This section should not replicate your requirements document, which you hopefully do have (if you do, provide the reference link, so it's easy to find.) Include a high-level overview that explains what you are building.
Highlight essentials that greatly influence design and architecture decisions and would be challenging and costly to retrofit if missed.
Quality Goals
Are you sure you are designing the right thing? How would you evaluate the quality of software architecture?
Ask your stakeholders to list 3-5 crucial quality goals in the order of importance - order is vital because they may compete with each other (i.e., security and usability). Use team workshops if needed.
Record the goals in this section and explain why (and by whom) they were chosen.
There are always multiple ways to implement a solution. Use Architecture Tradeoff Analysis Method (ATAM) to analyze and rate the architecture based on defined quality goals.
Once your proposal is complete, you should be able to demonstrate how your architecture and design decisions address these quality goals.
Stakeholders
Stakeholders may include developers, product owners, project managers, department heads, users - anyone who should be the target audience for the document you are writing.
Make sure you included all parties to avoid unpleasant surprises during release time.
Constraints
If your team has expertise in Java but not in Python, you have a technical stack constraint for the project.
Do you have a coding style guide? What about the engineering process (agile/waterfall, testing, and release procedures)?
Are there legal or security considerations?
Write down anything that not negotiable and may have a significant impact on architectural decisions and software implementation.
Context and scope
This section describes external interfaces that you must integrate with and could contain two subsections - business and technical contexts.
Business context uses domain-specific language and demonstrates the flow of data between the system under design and its neighbors (including end-users). For example, the business context may illustrate a user requesting a report.
The technical context identifies how the data flow occurs, showing supporting infrastructure and protocols (FTP, HTTPS, SSH, VPN, etc.). For example, it may specify that the user accesses the report using HTTPS.
It's critical to list all external interfaces that your system must support to function per requirements.
Solution Strategy
There are always multiple ways to design something. You've had to make quite a few decisions along the way: what technology to use, the composition of the system, should you build in-house, or outsource, reuse or start anew.
Record the decisions made and rationale behind them here - in my experience, it prevents "I don't remember why we decided that, but there were good reasons...right?" conversations and urges to refactor needlessly.
Building Block View
Your system consists of multiple building blocks: databases, services, frameworks, layers.
In the "Context and Scope" section, you've created an overall black-box view of the system under design, describing its external interfaces.
In this section, we want to zoom into the black box and look inside.
Describe a small architecture in a single diagram.
Create multiple views for broader architecture, starting at the top overview and zooming in to show more details. Alternate between black-box and white-box perspectives.
The black-box view should specify the purpose of the component and any relevant external interfaces.
The white box presents a black-box decomposition that can, in turn, include other black-box components.
Example: web application is a top-level view consisting of back-end API, front-end client app, and database layer.
Back-end API can be decomposed to middleware, reverse proxy, etc.
Runtime View
Your designed system is not static. It interacts with other systems via external interfaces. Multiple blocks that compose the system interact with each other during runtime. You should understand how these interactions occur and communicate that to your team.
Record the essential runtime views in this section, scenarios that are important from the architectural standpoint.
Some examples may include system start-up and shutdown, error handling, critical use cases.
Deployment View
This view illustrates the deployment plan for constructed software—document hardware infrastructure - nodes, connections, accessories, network topography. Include the physical location of your hardware, if applicable. Then document how software components are build and distributed to specific nodes.
Record build automation specifics.
Cross-Cutting Concepts
Catch-all section for decisions, guidelines, tactics, rules that impact multiple parts of the system architecture. It should only include high-quality topics. Treat the section as a developer cookbook. The generic list to pick from may include:
- UX (usability, internationalization, accessibility, testing, style rules)
- Security
- Design patterns
- Operations (logging, deployment, monitoring)
- Development (build and configuration management, automated testing)
- Domain-specific concepts
- Anything else (error handling, business rules, reporting)
Architecture Decisions
The section looks redundant - aren't most technical decisions documented under Solution Strategy?
It is optional.
Did you make a risky decision that may affect multiple stakeholders, be very costly, and change the future technical roadmap?
Use this section to highlight it, listing all possible alternatives you had considered and reasons the risky solution had won.
Quality
List additional quality goals (that didn't make the top 3 list) here.
Use quality scenarios to measure and verify that software architecture satisfies quality goals.
Quality scenarios describe how the system should react when a specific event occurs. The reaction should be measurable.
For example
- The user requested data from the system. The system displays the data within 5 seconds.
- The external system had failed. The system reports the failure within 30 seconds.
Risks and Technical Debt
This section is excellent for recording recognized problems that may affect your project, whether organizational, business, or technical.
Mention any risks brought out by architectural decisions and how you are planning to mitigate it - this is especially important for non-technical stakeholders, like the project and product managers.
If you are running Software FMEA, include results here.
Glossary
Make sure everybody on the team speaks the same language.
Explain abbreviations used throughout the document. Include domain-specific and technical terms.
Parting words
Less documentation is quicker to read, easier to maintain. But "less" doesn't mean "none." Proper documentation improves team communication and saves time in the future, trying to reverse engineer the architecture from the completed project.
Following the template facilitates architecture validation, and mistakes are much easier to correct during the design stage.
Think long-term. Would this matter to anybody in a month? If not, do not document it.