Architecture Documentation
What to write down, at what altitude, and what nobody will ever read.
4 to work through
-
intermediate
A database platform team is asked why a decade-old partitioning scheme was chosen. Nobody remembers, the original architects have left, and the only artefact is a diagram with no rationale. What failed here, and what document would have prevented it?
2 min answer -
intermediate
A developer-tools company has a fifty-page architecture document that nobody reads and a set of diagrams that are eight months stale. What should be written instead?
1 min answer -
intermediate
You are leaving a project in two days and have two hours to document the system. What do you write and what do you deliberately leave out?
2 min answer -
intermediate
Your team maintains a 90-page architecture document that is always out of date and nobody reads. What should replace it?
1 min answer
3 terms in this topic
Architecture Documentation
Writing down the decisions and their reasoning at an altitude that stays true long enough to be worth reading.
conceptArchitecture Viewpoint
A perspective on a system tailored to the concerns of a particular audience, recognising that no single diagram serves everyone.
conceptDocumentation Half-Life
The observation that architecture documentation decays in proportion to how much it restates current structure, and that the artefacts which survive …
Neighbouring topics
Architecture Fundamentals
General material on what solution architecture is and what an architect is accountable for.
Requirements to Constraints
Turning stated requirements into the constraints that actually bound a design.
Functional vs Non-Functional
Behaviour versus quality of behaviour, and why only the second constrains structure.
Architectural Drivers
The small subset of requirements whose change would force the structure to change.
Quality Attributes
Availability, latency, throughput, security, cost — expressed as testable scenarios.
Architecture Principles
Durable agreed rules that rule options out, stated with rationale and implications.
Coupling
How much one component must know about, or change alongside, another.
Cohesion
Whether the things inside a boundary belong together and change for the same reason.
Modularity
Composing a system from parts that can be understood and replaced independently.
Separation of Concerns
Organising so that a change to one concern touches one place.
Abstraction & Encapsulation
Hiding mechanism behind contract, and protecting invariants by owning state.
Architecture Styles
System-level organising shapes, and how they differ from problem-level patterns.
Evolutionary Architecture
Designing for guided incremental change rather than for correctness on day one.
Fitness Functions
Automated checks that an architectural characteristic still holds.
Conway's Law
Systems mirroring the communication structure of the organisation that builds them.
Trade-off Fundamentals
Why every architecture is a set of purchases, and how to state what you gave up.
Technical Constraints
Existing estate, skills, licences and platforms as inputs rather than obstacles.
Architecture Roles
Solution, enterprise, domain and platform architecture, and where each is accountable.
Reference Models
Shared conceptual frames — layering, tiers, viewpoints — and their limits.