Documenting the software architecture design
Practice · Chapter 5
Two things to capture during design
Section titled “Two things to capture during design”Documenting design means recording the many decisions made — usually by sketching architecture views and documenting the design rationale. This informal documentation happens during design; the formal documentation comes later (see Creating architecture descriptions (ADs)).
Sketching the architecture design
Section titled “Sketching the architecture design”- Architecture views represent an architecture to communicate it to stakeholders. Because an architecture is too complex for one comprehensive model, you need multiple views.
- Formal views come afterward, but informal sketches should be made during design — recording structures, elements, relationships, and the design concepts used.
- Sketches need no formal notation, just clarity. Sketch at least the important decisions and elements — whiteboard, paper, or a modeling tool.
- Benefits: they make later formal views easier to produce, ensure no design detail is forgotten, and help explain later how requirements and quality attributes were satisfied during review.
- Diagnostic value: if you can’t sketch a part of the design, that signals it’s poorly understood, too complex, or unclear — revisit it until you can. A design you can sketch effortlessly is one your audience will grasp.
Documenting the design rationale
Section titled “Documenting the design rationale”A design rationale explains the reasons and justification behind decisions — something sketches (which show what was designed) don’t convey. It can also record decisions not made, alternatives considered, and why each rejected alternative was rejected.
- Value: capturing rationale clarifies the architect’s own thinking (and can expose flaws in it); afterward, anyone (including the original architect, who may forget) can learn why a decision was made.
- Tie rationale to the specific structures designed and the requirements they meet. Some design tools help capture it.
- A complete rationale is a history of the design process, useful for six purposes:
| Use | How the rationale helps |
|---|---|
| Evaluation | Compare competing designs and understand when one is chosen over another. |
| Verification | Confirm the designed system is the intended one — that it meets requirements and quality attributes and works as expected. |
| Knowledge transfer | Onboard team members (present and future), especially when original designers are gone. |
| Communication | Add value when explaining the architecture to stakeholders and reviewers. |
| Maintenance | Locate what to change, spot weaknesses, and know why prior decisions/alternatives were made or rejected. |
| Reuse | Support architecture reuse across a product line — understand what’s reusable and where variation points allow safe adaptation, preventing harmful modifications. |
Related concepts
Section titled “Related concepts”- Creating architecture descriptions (ADs)
- Reviewing software architectures
- Using a systematic approach to software architecture design
- Software product lines
Citations
Section titled “Citations”- Software Architect’s Handbook (Packt, 2018), Ch.5 “Documenting the software architecture design”, pp. 319-329.