Uses of Software Architecture Documentation
Practice · Chapter 12
Why bother documenting?
Section titled “Why bother documenting?”Many projects skip architecture documentation, treat it as an afterthought, or only produce it because a process or contract demands it. Good architects instead treat documentation as a first-class deliverable because it pays back across the whole project life cycle. An architecture only has value if it can be communicated to the people who must build, use, and change the system.
The six core uses
Section titled “The six core uses”| Use | What it buys you |
|---|---|
| Communicate the architecture | Conveys the system’s structures and their interactions to technical and non-technical audiences alike. |
| Assist the development team | Shows interfaces, elements, and constraints so developers know what to build, what to reuse, and which decisions are already fixed. |
| Educate team members | Onboards new joiners and helps existing developers understand the design decisions behind what they are working on. |
| Provide input for reviews | Supplies the detail reviewers need to evaluate an architecture against requirements and quality attribute scenarios, and to compare alternatives. |
| Reuse architectural knowledge | Preserves decisions, rationale, and lessons learned so they can be leveraged on other systems. |
| Help the architect | Answers the flood of stakeholder questions and serves as external memory. |
Communicating to different stakeholders
Section titled “Communicating to different stakeholders”- Different stakeholders (developers, management, other stakeholders) care about the architecture for different reasons and priorities.
- An architecture is abstract enough that many audiences can reason about the system from it.
- Different architecture views target different audiences — no single artifact serves everyone. See Creating Architecture Descriptions (ADs).
Assisting and constraining developers
Section titled “Assisting and constraining developers”- Documentation communicates design decisions, preventing developers from making the wrong implementation choices.
- Architecture deliberately restricts design freedom and constrains implementation — reducing overall system complexity.
- Seeing available interfaces tells developers what to implement versus what is ready to consume.
Keep it current
Section titled “Keep it current”- When the architecture changes, the documentation must change with it; stale docs mislead the team.
Feeding reviews and enabling reuse
Section titled “Feeding reviews and enabling reuse”- Review teams use documentation to check whether functional requirements and quality attribute scenarios can be met, and to compare candidate architectures.
- Reuse is especially valuable across a software product line, where products share functional/non-functional requirements and look-and-feel; parts of one product’s architecture can serve others.
Helping the architect specifically
Section titled “Helping the architect specifically”- Acts as external memory for complex systems revisited months or years later.
- Supports pitching a project, securing funding, and giving presentations.
- Preserves answers if the architect leaves the project or organization.
Citations
Section titled “Citations”- Software Architect’s Handbook (Packt, 2018), Ch.12 “Uses of software architecture documentation”, pp. 907-913.