Diagram Maintenance Economics

Diagrams decay at a rate proportional to how fast the thing they describe changes. A context diagram changes a few times a year; a component diagram changes weekly. Maintaining both by hand means one is accurate and one is a liability.

And a stale diagram is worse than no diagram, because it is trusted. Someone designs against it, estimates from it, or explains the system with it, and the error propagates. An absent diagram forces a conversation with someone who knows.

Why it matters

Documentation sets fail not through inaccuracy but through the useful pages becoming unfindable inside the useless ones. Deleting the low-value diagrams improves the set, which is counter-intuitive and reliably true.

Implementation patterns

• Maintain by hand: the context diagram. One page — the system, its users, its external dependencies. It is what new joiners, security reviewers and auditors actually need, and it changes rarely.
• Maintain the container diagram only if someone owns it. It is the most useful level for an operational conversation and it changes monthly, which is the boundary of hand-maintainability.
• Generate anything below that, or do not have it. Component structure is derivable from source, so a hand-drawn version adds only the possibility of being wrong.
• Draw sequence diagrams for the two or three genuinely difficult flows — those with unusual ordering, retries, compensations or cross-boundary coordination. These are the diagrams that earn their cost, because interaction under failure is precisely what cannot be derived from reading code.
• Apply the test to every diagram: who looks at this, when, and what decision does it change? Anything without an answer gets deleted.

Industry example

Developer-tools organisations such as Postman ship continuously across many surfaces and cannot keep component-level diagrams current. What their engineers need is the context boundary, a container view for operational discussions, and careful sequence diagrams of the handful of flows — sync, conflict resolution, authentication — that are genuinely hard.

Everything else is better read from the code, and attempting more produces a documentation set that is largely wrong.

Failure scenarios

• Hand-maintained component diagrams, wrong within a sprint and trusted anyway.
• Diagrams generated but never reviewed, so they are accurate and unreadable.
• A large set where the two useful diagrams are unfindable.
• No sequence diagram for the difficult flow, which is the one thing nobody can reconstruct.
• Diagrams as a deliverable rather than as a communication tool, produced for a process and consulted by nobody.

Trade-offs

Generated diagrams are always current and show what exists, never why. Hand-written ones can carry intent and go stale.

The division of labour that works: generate the structure, write the rationale. Then the generated artefacts cannot lie and the written ones do not need updating, because reasoning is stable in a way structure is not.

Interview question

"You inherit a documentation set with forty diagrams, most of them out of date. You have two days. What do you delete, what do you fix, and what do you automate?"