An architecture document is read by someone deciding whether the design holds up, and a diagram pasted in as a picture stops being true the moment the design changes.
Order service — system design
Orders enter through the gateway, are validated once, and are written to a single ledger before anything downstream sees them.
If the ledger is unreachable, the gateway queues writes for up to ten minutes and answers with an accepted status, not a success.
A system design document carries a diagram and a code sample, and both have to still be correct next quarter. Drawing the diagram inside the document rather than pasting it in as an image means updating a line instead of redoing an export.
Diagrams drawn in the document
The diagram carries an editor behind it, so an architecture drawing is edited rather than redrawn when a box moves.
Design files embedded, not screenshotted
A linked Figma frame updates when the file does, instead of going stale the day after it was pasted in.
Commands and numbers kept beside the diagram
A code sample keeps its own formatting instead of losing its indentation when it's pasted in, and a table of limits or capacities sits next to the diagram it explains, in the same document.
Which heading holds the deciding reader longest
One heading keeps a deciding reader longer than the rest — the diagram, the numbers, or the code around them — and whether they circle back to it before deciding.
An example — not your document. Sections are the document’s own headings.
Most of their attention went to “Drawing” — 2m 09s of 4m 00s.
Time each section spent on screen, counted only while the tab was in front and the reader was active. It shows what was in front of them, not what they read.
This page is about what a system design document has to do. For the blocks the editor is built from — see the editor.
No — it is for the document that follows the whiteboarding: the one that gets read and referred back to, with the diagram kept inside it rather than screenshotted in from somewhere else.
Not yet — several other document types already have templates, and the library keeps growing. A system design document starts from a blank page for now.