You are documenting a mid-size system and want a "minimum yet sufficient" architecture description. How do you decide how many views to produce, at what depth, and in what notation for each audience?
answer
- every page is a liability you must keep true
- closure both ways: no unframed concern, no concern-less view
- depth ∝ risk (importance × difficulty), never uniform
- notation per audience; always include a key
- test: would anyone decide differently because of this?
basics
~20 sDerive views from prioritized stakeholder concerns rather than from a template: one view per live, high-priority concern cluster. Go deep only where risk is high, keep the notation simple enough for the intended reader, and delete anything nobody would act on.
solid answer
~60 sTreat every page as a liability that must be kept true. The selection rule is the ISO/IEC 42010 closure rule read in both directions: no prioritized concern left unframed, no view without a live concern. Depth is set by **risk**, not by uniformity — go deep where the utility tree marks a scenario as high business importance *and* high architectural difficulty, and stay at a single diagram elsewhere. Notation is set by **audience**: sponsors get a one-page context diagram and a decision list; developers get interfaces and responsibilities; operators get node, port, and run-book detail; assessors get data classification and control mapping. Prefer few, layered artifacts (a C4-style zoom, or a context plus container plus one or two component drill-downs) over many flat ones. Add cross-cutting qualities as perspectives applied to existing views rather than as new views. Record correspondences between views, known inconsistencies, rationale for major decisions, and the concerns you deliberately did not address. Finally, test each artifact: if no one would make a different decision because of it, cut it.
go deeper
Say views should come from what stakeholders need to know, not from a template, and that a diagram nobody uses should be deleted. Mention tailoring the level of detail to the reader.
Give the both-directions closure rule, tie depth to risk, and map two or three audiences to what they need (sponsor overview, developer interfaces, operator deployment detail).
Add the maintenance-cost argument, utility-tree-driven depth, layered zoom notation with keys, correspondences and recorded inconsistencies, rationale and ADRs, and explicit recording of deliberately unaddressed concerns.
Frame it as an organizational policy question: a shared viewpoint library and ADR practice, what is generated versus curated, review and retirement cadence, how the sufficient bar shifts for regulated, outsourced, or decades-long systems, and how to prevent the practice from degenerating into documentation theatre.
## The economics that drive the answer Architecture documentation has two costs: the one-off cost of producing it and the recurring cost of keeping it consistent with a moving system. The second dominates. A description that is 60% accurate is worse than a smaller one that is 100% accurate, because readers cannot tell which 40% is lying. So "minimum yet sufficient" is not laziness — it is the only regime in which documentation stays trustworthy. ## Rule 1 — selection: derive, never default Start from the prioritized concern list (see stakeholder elicitation) and apply the closure rule in **both** directions: - **Forward:** every prioritized concern must be framed by at least one view (or by a cross-cutting perspective applied to views). - **Backward:** every view must frame at least one live concern. If you cannot name the stakeholder and the concern for a view, delete it. A useful blunt heuristic: for each candidate view, ask *"who would make a different decision tomorrow because this exists?"* If the honest answer is nobody, it is decoration. Typical outcome for a mid-size system: a Context view, a Functional/Container view, one Information view (if data ownership, retention, or consistency is a real concern), a Deployment view, and an Operational view — with Concurrency and Development produced only when threading or multi-team build structure are actual pain points. Cross-cutting qualities (security, performance, availability, evolution) are applied as **perspectives** that annotate those views rather than as views of their own. ## Rule 2 — depth: uniform depth is always wrong Depth should track risk. Use the ATAM-style **utility tree** tags — business importance × architectural difficulty — and drill down only in the (High, High) cells. Concretely: - **Deep** (interfaces, protocols, failure modes, numbers): the two or three elements that carry the hardest quality scenarios, the parts that are expensive to change, and the parts crossing team or organizational boundaries. - **Shallow** (one box, one sentence of responsibility): well-understood CRUD areas, off-the-shelf components, anything a competent reader can infer. - **Zero**: things that change weekly and are better read from the code or from live infrastructure descriptions. A good instinct: document what is **hard to reverse** and what is **hard to discover from the code**. Class-level structure is discoverable from the code and volatile — leave it out. Regional failover topology is neither — write it down. ## Rule 3 — notation and framing: per audience, not per author The same underlying model should be rendered differently for different readers. A workable mapping: | Audience | Wants | Good form | |---|---|---| | Sponsor / acquirer | Scope, cost drivers, big risks | One-page context diagram + top decisions and risks | | Product / users | Capabilities and boundaries | Context + functional responsibilities in domain language | | Developers | Responsibilities, interfaces, dependency rules | Container/component diagrams + interface contracts + ADRs | | Operators / SRE | Nodes, ports, scaling, failure and recovery | Deployment diagram + node table + run-book links | | Testers | Seams, environments, test data | Functional + deployment with test-hook annotations | | Assessors / auditors | Data classes, controls, boundaries | Information view with classification + control mapping | | Maintainers | Why it is like this | Rationale, ADRs, rejected alternatives | Practical notation guidance: prefer a **layered zoom** (context → container → selected component) over many unrelated diagrams; keep a visible legend rather than assuming shared symbol knowledge ("a diagram needs a key" is the single most-violated rule); use a formal notation like UML only where its precision is actually used, otherwise boxes-and-lines with an explicit key is fine; and keep each diagram to roughly one screen with a stated purpose sentence. ## Rule 4 — glue: correspondences, rationale, and honest gaps Multi-view descriptions fail by drifting apart. ISO/IEC 42010 asks you to record **correspondences** and **correspondence rules** between views ("every functional element appears on at least one node"; "every externally reachable interface has a documented authentication mechanism") and to record **known inconsistencies** rather than pretending they do not exist. Add **rationale**: the decision, the alternatives rejected, and why — that is what maintainers need most and what is lost fastest. Also record the negative space: concerns you consciously did not address, and the trigger that would change that ("no multi-region view: single-region until latency SLO for EU customers is contractual"). ## Rule 5 — keep it alive or kill it - Tie updates to change: an ADR per significant decision costs minutes and ages well; a 60-page document does not. - Generate what can be generated (dependency graphs, module diagrams, API specs) so it cannot drift. - Review the view set at milestones; retire views whose concern has died. - Store it where the readers already are, versioned alongside the code where possible. ## Trade-offs and edge cases - **Regulated or safety-critical domains** shift the balance hard toward more and deeper views, because assessors are stakeholders whose concern is literally "is it documented and traceable?". Minimum-yet-sufficient still applies; the sufficient bar is just much higher. - **Hand-off and outsourcing** raise the bar too: the receiving team has none of the tacit knowledge that lets a co-located team get away with three diagrams. - **Long-lived systems** justify rationale far more than diagrams — in ten years the structure is readable from the code but the reasoning is gone. - **Over-correction risk**: "the code is the documentation" fails for cross-cutting structure, deployment topology, and rationale, none of which any single file contains. - **Generated vs curated**: generated artifacts are always true but rarely explain anything; curated ones explain but rot. Use both deliberately.
- How do you keep several views consistent with each other as the system changes?Define explicit correspondence rules between views (every functional element maps to at least one deployment node; every external interface has a named authentication mechanism), check them at review time or automatically where the models are machine-readable, generate whatever can be generated so it cannot drift, keep the curated set small enough to re-read in one sitting, and record known inconsistencies openly rather than letting readers discover them. Tying each significant change to an ADR keeps rationale current at low cost.
- When is heavy, deep documentation genuinely the right call?When assessors or regulators are first-class stakeholders and traceability is itself a requirement; when the system is safety-critical; when it will be handed to a different organization or maintained by people with no tacit context; when the lifetime is measured in decades; or when many teams integrate against it and the interface contracts are the product. In those cases the sufficient bar rises, but the derivation rule is unchanged.
- What content ages best, and what ages worst?Rationale and decision records age best — the reasoning behind a choice stays useful long after the code changes, and it cannot be recovered from the code. Context and boundary descriptions age well. Deployment topology ages moderately. Class-level and low-level structure ages worst: it is volatile and already discoverable from the source, so writing it by hand is pure liability; generate it if you need it.
A city gives a homeowner a plot map, a builder full structural drawings, and a fire marshal only the egress and sprinkler details — all rendered from the same underlying model at different depths. Nobody hands the homeowner the rebar schedule, and nobody expects the fire marshal to infer exit routes from the paint schedule.
saying these in an interview costs you the question
- Producing every view in the chosen viewpoint set for completeness, without naming a stakeholder and concern for each.
- Documenting at uniform depth, spending as much effort on a CRUD area as on the hardest availability scenario.
- Hand-writing class-level detail that is volatile and already visible in the code.
- Diagrams with no key, no purpose sentence, and mixed levels of abstraction on one page.
- Omitting rationale and rejected alternatives — the content that ages best and is impossible to recover later.
- Claiming "the code is the documentation" for deployment topology, cross-cutting structure, or the reasoning behind decisions.
- Never retiring views whose motivating concern is dead, so the set grows monotonically and rots.