A team produces detailed component diagrams for every service and they are all stale within a sprint. Which diagram levels are worth maintaining by hand?
Show the full answer Hide the answer
The levels and their economics
- Context (level 1): the system, its users, and the external systems it depends on. One page. Changes a few times a year. Worth maintaining by hand, and it is what new joiners, security reviewers and auditors actually need.
- Container (level 2): the deployable units and the technology and communication between them. Changes monthly. Worth maintaining if and only if someone owns it, and it is the level most useful for an operational conversation.
- Component (level 3): the internals of one container. Changes weekly. Generate it or do not have it. A hand-maintained component diagram is wrong within a sprint and worse than absent, because it is trusted.
- Code (level 4): never draw this. The IDE does it better and it is always current.
Why detailed diagrams are worse than no diagram
A stale diagram is trusted. Someone will design against it, estimate from it, or explain the system with it, and the errors propagate. An absent diagram forces a conversation with someone who knows, which produces a correct answer.
What to draw instead of level 3
A sequence diagram for a specific interesting flow. The two or three flows that are genuinely difficult — the ones with unusual ordering, retries, compensations or cross-boundary coordination — are worth drawing carefully, because they are what nobody can reconstruct from the code without hours of work.
A diagram earns its maintenance cost when it explains something that is hard to derive from the source. Structure is easy to derive; interaction and rationale are not.
The test to apply to any diagram
Who looks at this, when, and what decision does it change? A diagram with no answer gets deleted. Applying this honestly usually removes most of a documentation set and improves it, because the failure of large diagram collections is not inaccuracy but that the useful ones are unfindable inside the rest.