Think of this chapter as a library card catalog: the architecture is the whole collection, and documentation is the cataloging system that lets every stakeholder find exactly the view they need.
A system's architecture may be the single biggest determinant of success or failure. But an architecture that only lives in one person's head might as well not exist — communicating it is as important a job as designing it.
No documentation reaches them at all — the architecture is effectively invisible.
Documentation exists but isn't clear enough to build, use, or modify the system with.
They read it, get the wrong idea, and apply the architecture incorrectly — often the costliest failure.
Choose a set of relevant views → document each view → document information that spans more than one view (or the whole set). That's the entire job, in one sentence.
Introduces new people to the project — the on-ramp for anyone joining.
Keeps every stakeholder — up, down, and across the org chart — on the same page.
Lets you (or a reviewer) verify the quality attributes are actually going to be met.
Four questions to answer before producing any documentation — remember them as Views → Who → Worries → Write-up.
Decide which architectural views (see the 4+1 model below) are actually worth documenting for this system.
Who is this documentation for? Managers, developers, testers, and customers all need different things.
What does each stakeholder actually need to know? Build a table mapping stakeholder → concern → view.
Pick a template (e.g. RUP or SEI) that structures the content consistently.
Every card in the catalog has a different patron. Sample stakeholders you'll typically document for:
Tracks progress & risk
Builds within the design
Verify behavior & fit
Modify it long-term
Reuses across products
Confirms it meets needs
Cares about the outcome
Assesses quality attributes
Runs & hosts the system
Owns & evolves the design
Build a table like this — it lets you prioritize views by whose concerns carry the most weight.
| No. | Stakeholder | Concern to address | Suitable view |
|---|---|---|---|
| 1 | Project Manager | e.g. Is the schedule realistic? | Development view |
| 2 | Maintainer | How do I change module X safely? | Development / Logical |
| 3 | Infrastructure Support | Where does each service run? | Physical view |
| 4 | Analyst | Will it handle peak load? | Process view |
| 5 | End User | Does it support my workflow? | +1 Use-case view |
Several view-set approaches exist (Siemens Four Views, Herzum & Sims, the SCR method) — but Kruchten's 4+1 is the most widely used, and the one we focus on.
Behavioral requirements. Key abstractions — objects and object classes. (the floor plan)
Concurrency & distribution — maps threads to objects. (the traffic flow)
Organization of modules, libraries, subsystems, units of development. (construction packages)
Maps elements onto processing & communication nodes. (the site map)
Maps the other four views onto key use cases to show how they work together. (the guided tour)
| Approach | Views it defines |
|---|---|
| Siemens Four Views | Conceptual · Module interconnection · Execution · Code |
| Herzum & Sims | Technical · Application · Project management · Functional architecture |
| Software Cost Reduction (SCR) | Module view (modifiability) · Process view (performance) · Uses view (incremental development) |
Choosing a view set means understanding stakeholder needs, how they'll actually use the documentation, and the resources you have available — not just picking every view that exists.
Once you know your views, stakeholders, and concerns, pick a template to structure the write-up. Two common ones:
Introduction → Architectural Representation → Goals & Constraints → Use-Case View → Logical View → Process View → Deployment View → Implementation View → Data View → Size & Performance → Quality.
Documentation Roadmap → Stakeholder Representation → Viewpoint Definitions → Architecture Background (problem + solution) → Views → Directory (index, glossary, acronyms).
A software architecture document should contain the minimum information necessary to understand the system — but no more than that.
Every view — Logical, Process, whichever — gets documented the same way, with up to five parts.
Usually graphical ("the cartoon"), sometimes a table. Includes a key/legend and shows the elements + relationships you most want to convey. Often all a reader gets — but rarely enough on its own.
Explains every element in the picture: their properties, their relations, any exceptions, and their interfaces.
Shows how this view — or the part of the system it covers — relates to its surrounding environment.
Explains how to exercise any variation points left unbound until a later development stage.
The rationale for this view's decisions — including rejected alternatives, analysis results, and assumptions about the environment and the need being met.
Some information doesn't belong to just one view — it applies across the whole set, like the drawers of the catalog cabinet itself.
How the docs are organized per stakeholder — a list of views plus scenarios for which parts to consult.
Explains how each view is documented, and the standard organization used for all of them.
A short prose description of the system's function, users, background, and constraints — a shared mental model.
Useful correspondences between views, often captured as tables.
Architectural decisions that span multiple views — background constraints, major requirements, and which fundamental patterns were chosen.
Reference material for quick lookup: index of terms, glossary, acronym list.
Quality attribute requirements need their own paper trail — every one of them has a constituency of stakeholders who need proof it will be satisfied.
The document should explain why a design approach was chosen, and discuss the tradeoffs among competing quality attributes.
Architectural elements providing a service often get explicit quality-attribute bounds assigned to them.
Documentation often maps requirements — including quality-attribute requirements — to how the architecture satisfies them.
Quality attributes should be clearly and explicitly identified — never left for the reader to infer.
| Question | Answer |
|---|---|
| Why document? | An architecture no one can find, understand, or apply correctly might as well not exist. |
| What are the 3 uses? | Education, Communication, Analysis — "Teach it, Talk it, Test it." |
| What's the planning order? | Views → Who (stakeholders) → Worries (concerns) → Write-up (template). |
| Which view model do we use? | Kruchten's 4+1: Logical, Process, Development, Physical, +1 Use-Case. |
| How do you document one view? | Primary Presentation, Element Catalog, Context Diagram, Variability Guide, Architecture Background. |
| What spans multiple views? | Roadmap, View Documentation, System Overview, Mapping, Rationale, Directory. |
| How much documentation is enough? | The minimum necessary to understand the system — no more. |
tap a card to flip it