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
What format do diagrams export in for a doc?
SVG, which stays sharp at any zoom, and PNG where a tool insists. SVG is the better choice for anything that might be read on a large screen.
Can it write the document too?
It writes a markdown specification from the diagram, which covers structure. The reasoning, the alternatives you rejected and why, is yours and is the part worth reading.
Does this replace an ADR?
No. An ADR records a decision and its context; a diagram records a structure. They are complementary and neither substitutes for the other.
Related
- Migration PlanningMigrations fail on the intermediate states, which is exactly the part nobody draws.
- Offline and Air-Gapped TeamsEvery other tool in this category is a web application. If your code cannot go to a browser, that rules all of them out.
- Keeping Diagrams in Sync with CodeEvery architecture diagram is accurate on the day it is drawn. The question is what happens in month four.
- Open Source MaintainersMost first-time contributors give up before opening a pull request, and a surprising share of that is not knowing where anything is.
Last updated