Writing technical design documents.
The diagram in a design doc usually gets drawn last, badly, because everyone is tired of the document by then.
The situation
A design document is mostly prose describing structure, which is the thing prose is worst at. The diagram that would carry it in one glance gets added at the end, drawn quickly in whatever tool is open, and is the first thing to become wrong when the design changes during review.
Draw first, write around it
Producing the diagram first and writing the document around it inverts the usual order and produces better documents, because the act of drawing forces the structural decisions to be made explicitly rather than left ambiguous in a sentence. The prose then explains the diagram instead of substituting for it.
Changing it during review is cheap
Design documents change during review, which is the point of review, and a hand-drawn diagram is where that change is expensive. With computed layout, restructuring is an edit to the graph, so the diagram tracks the discussion rather than lagging a week behind it.
Then it becomes the specification
Once the design is agreed, the same diagram converts into a markdown specification and starts a coding turn. That closes the usual gap where the document is approved and the implementation is written from someone's recollection of it.
Design first
Questions
Related
- Onboarding Engineers to a CodebaseThe first week is spent building a mental model that somebody already has. A diagram transfers it in an afternoon.
- Documenting Legacy CodeIncluding the newest kind of legacy code: what a coding agent wrote for you over several sessions that nobody has looked at as a whole.
- Architecture ReviewMost of the effort in an architecture review goes into producing the diagrams, and most of those diagrams describe the system as remembered rather than as built.
- System Design Interview PreparationThe diagram is the easy part. Interviews are decided by the tradeoffs you can defend when the interviewer pushes.