A design tool's architecture document contains fourteen diagrams and reviewers still ask basic questions. What makes a diagram earn its place?
Show the full answer Hide the answer
What makes a diagram earn its place
It answers a question the reader has, that prose would answer worse.
Most architecture diagrams fail that test. They show boxes and arrows that a paragraph would describe more precisely, while omitting the thing the reader wanted to know.
The diagrams that earn their place share properties:
1. One question per diagram. "How does a request flow through the system" and "what is deployed where" are different questions and must be different diagrams. A diagram answering both answers neither.
2. A legend, and consistent notation. If a solid arrow means synchronous and a dashed one asynchronous, say so. Undocumented notation is decoration, and readers will assume conventions that are not there.
3. Labelled arrows. An unlabelled arrow between two boxes carries no information beyond "these are related". What flows, in which direction, synchronously or not, and what happens if it fails — that is the content.
4. Boundaries that mean something — trust boundaries, deployment boundaries, team ownership — stated explicitly rather than implied by a rectangle.
5. Deliberate omission. A diagram showing every component shows nothing. Whatever is not relevant to the question should be absent, and the omission should be acknowledged.
Why fourteen diagrams produce basic questions
Because none of them establishes context. Readers who do not know what the system is, who uses it, and what it connects to cannot absorb component detail — they are asked to parse mechanism before they have a model to hang it on.
The usual remedy is to start with one system-context diagram showing the system as a single box with its users and external dependencies, and only then decompose. That single diagram removes most of the basic questions, and it is the one most often missing.
The test
Show the diagram to someone unfamiliar and ask them to explain it back. Where they hesitate, the diagram is not communicating — and the hesitation locates the problem precisely, which no amount of self-review does.
The practical rule
A document with fourteen diagrams almost certainly has three that matter and eleven that dilute them. Deleting diagrams usually improves an architecture document, because each one competes for the reader's limited attention and the important ones lose.