You are asked to document the architecture of a new system and you can only produce three artefacts. How do you decide which views to write, and how do you match each to a stakeholder concern?
answer
- Stakeholders → concerns → views, never diagrams first
- Rank by risk × frequency × non-recoverable-from-code
- Default three: container, deployment, scenario walkthrough
- Name the reader, the decision, the trigger, the owner
- Diagrams show what; ADRs show why
basics
~20 sStart from stakeholders and the questions they actually ask, not from a diagram template. Pick the views that answer the highest-risk or most-asked questions — usually a context/container-style structural view, a deployment view, and a walkthrough of one or two critical scenarios.
solid answer
~50 sWork backwards from concerns. List the stakeholders (product, developers, ops/SRE, security, support, new joiners) and write down the concrete questions each keeps asking. Rank those questions by risk and frequency, then choose the minimum set of views that answers the top ones. In practice the three that pay off most often are: (1) a **context + container view** — what the system is, who uses it, which deployable parts and data stores exist and over which protocols they talk; this serves onboarding, product and dev; (2) a **deployment view** — nodes, replicas, regions, failover — which serves ops, security and cost owners and is the one nobody can reconstruct from code; (3) a **dynamic/scenario walkthrough** of the one or two architecturally significant flows (peak-load path, auth flow, failure path), which validates the other two. Then state coverage gaps explicitly, and pair the set with ADRs for rationale.
go deeper
Say you would ask who reads it and what question it answers, and name the obvious high-value artefacts: an overview of the parts and how they talk, and where things are deployed.
Show the stakeholder → concern → view chain with concrete example questions per role, and justify the three you pick.
Add ranking by risk and non-recoverability, the fit-for-purpose tests (reader, decision, trigger, owner), the swap rules when concurrency or data is the dominant risk, and pairing with ADRs.
Discuss organisation-level policy: a standard viewpoint catalogue and house notation, explicit coverage of concerns with recorded gaps, ownership and review cadence, the maintenance economics of documentation, and how the documentation set feeds architecture review and audit.
## The wrong starting point The common approach is "which diagrams should we draw?" — pick a framework, produce its full set, and file it. This fails predictably: the volume of documentation is set by the template rather than by demand, most of it is never read, and all of it decays. The maintenance cost is real and permanent, while the value is concentrated in a few artefacts. ## The right starting point: stakeholders → concerns → views This is the flow ISO/IEC/IEEE 42010 formalises and that every practical method (Rozanski & Woods, arc42, C4) follows in spirit. ### Step 1 — enumerate stakeholders Typical set: end users/product owners, developers on the team, developers on *other* teams who integrate, operations/SRE, security and compliance, support/on-call, testers, finance/cost owners, new joiners, and auditors or regulators where applicable. ### Step 2 — capture their real questions Don't guess: harvest them. Sources include onboarding questions from the last three new hires, the questions asked in incident post-mortems, the questions security asks at review, and the ones repeatedly answered in chat. Examples: | Stakeholder | Typical concern | |---|---| | New joiner / product | What is this system, who uses it, what does it depend on? | | Developer | Where do I add feature X? What talks to what, and how? | | Integrating team | What is the external interface and its protocol? | | Ops / SRE | What runs where, how many instances, what happens when a node/region dies? | | Security | Where are the trust boundaries, where does sensitive data flow and rest? | | Support / on-call | For this symptom, which component and which machine do I look at? | | Performance owner | Where is the concurrency, which calls are synchronous, where are the queues? | | Finance | What drives the running cost? | ### Step 3 — rank by risk × frequency A concern is worth a view if the answer is (a) frequently needed, (b) expensive to get wrong, and (c) **not trivially recoverable from the code**. That third criterion is decisive: class structure is recoverable by reading the repo, but deployment topology, trust boundaries and the *reason* for a split are not. ### Step 4 — choose the minimum covering set With a three-artefact budget the usual answer is: 1. **Structural overview (context + container, in C4 terms; roughly logical + development in 4+1).** Highest readership, longest shelf life, serves the most stakeholders per unit of effort. Label technologies on elements and protocols on arrows or it degrades into ambiguous boxes. 2. **Deployment view (4+1 physical / C4 deployment).** Nodes, instance counts, regions, network boundaries, data stores. Serves ops, security, cost and on-call, and is the least reconstructible artefact. 3. **One or two scenario walkthroughs (4+1 "+1" / C4 dynamic diagram).** Pick the architecturally significant flows: the highest-volume request path, the authentication/authorisation flow, and one failure/recovery path. Scenarios are deliberately redundant with the other views, and that redundancy is what exposes contradictions between them. If the system's dominant risk is concurrency (real-time, high-throughput, event-driven), swap artefact 3 for an explicit **process/concurrency view**; if the dominant risk is data (regulated personal data, complex ownership), swap in an **information/data view** showing ownership, flow and residency. ### Step 5 — record the gaps List the concerns you chose *not* to cover and why. An acknowledged gap is manageable; an invisible one is a surprise during an incident or an audit. ### Step 6 — add rationale separately Diagrams show structure; they cannot show *why*. Pair the views with **Architecture Decision Records** — short, dated, immutable records of context, decision, alternatives and consequences. In practice the pairing of "container diagram + deployment diagram + ADR log" outperforms a thick document set. ## Fit-for-purpose tests For each candidate view ask: - **Who is the named reader?** If you cannot name a role, don't draw it. - **What decision or action does it enable?** If none, it is decoration. - **What event should trigger an update?** (New container, new node type, new integration.) No trigger means guaranteed drift. - **Who owns it?** Unowned diagrams rot. - **Could the reader get this faster from the code?** If yes, generate it instead. ## Trade-offs to name in an interview - **Completeness vs currency.** Fewer, correct views beat many stale ones; a stale diagram is worse than none because readers act on it. - **Abstraction level vs churn.** Higher-level views change less; that is why context/container survive and code diagrams do not. - **Standardisation vs fit.** A house style (everyone uses C4) makes diagrams comparable and reviewable across teams, but a fixed template can miss a system-specific concern; leave room for extra views. - **Audience mixing.** One diagram for both executives and developers usually serves neither; that is precisely the split C4 encodes as levels. ## A concrete worked example A payments service handling card transactions across two regions: the three artefacts would be (1) a container diagram showing the API service, ledger database, event broker, reconciliation worker and the external card network, with protocols; (2) a deployment diagram showing both regions, replica counts, the database primary/replica arrangement and the trust boundary at the PCI zone; (3) a dynamic diagram of an authorisation-and-capture flow including the timeout/retry path. Security's concerns are then addressed as a *perspective* applied over views 1 and 2 rather than a separate diagram, and every non-obvious split (why reconciliation is a separate worker) is an ADR.
- Which single diagram would you keep if you could keep only one?The container-level structural view: it names the deployable parts, their technologies and how they communicate, so it serves onboarding, development, integration and operations at once, and it changes slowly enough to stay accurate.
- How do you stop the chosen views from going stale?Give each an owner and an explicit update trigger tied to real events (adding a container, a node type or an integration), keep the model as code in the same repository so it goes through code review with the change, and prefer generating anything volatile rather than hand-drawing it.
- A stakeholder's concern is 'is this system secure?'. Do you draw a security view?Usually no. Security is a cross-cutting perspective: annotate trust boundaries and data classification on the container and deployment views, walk an authentication scenario, and record decisions in ADRs. A standalone 'security diagram' tends to duplicate structure while answering nothing specific.
Like packing for a trip with one carry-on: you don't pack the full catalogue of clothing categories, you pack for the specific weather and activities you actually expect, and you write down what you consciously left behind.
saying these in an interview costs you the question
- Producing the full set of a framework's diagrams because the framework lists them
- Drawing views with no named reader and no decision they support
- Documenting what is trivially recoverable from the code while omitting deployment topology and trust boundaries
- Believing diagrams can carry rationale — that is what ADRs are for
- One diagram aimed at both executives and engineers
- No owner and no update trigger, so the set is stale within a quarter
- Leaving unaddressed concerns implicit rather than listing them as known gaps