An RFC is written to be argued with, and the argument only helps if it ends somewhere everyone can find again later.
RFC 014 — Event replay
This proposes replaying events from the durable log instead of re-querying upstream services, trading storage for a simpler recovery story.
Re-querying upstream on every recovery is simpler but couples us to five services’ uptime; snapshotting was rejected for storage cost.
Whether it is called a design doc or an RFC, it exists to get a decision reviewed before anything gets built, which means the alternatives that were set aside have to survive on the page next to the one that won. The record of that argument matters as much as the choice itself — someone who joins the project six months later should be able to see why, not only what. None of that helps if last month's version of the decision is the one a search turns up.
The decision, set apart from the case for it
What was decided sits apart from the reasoning behind it, so a reviewer scanning for the outcome does not have to trace the whole argument to find it.
Alternatives kept on the page, not just the one that won
Options that were considered and set aside stay in the document next to the one that was chosen, so nobody has to reconstruct a conversation nobody wrote down.
Comments that get resolved, not just posted
A question on a paragraph is marked resolved once it is answered, and reopened if someone disagrees later, so a reviewer can tell which parts of the argument are still open.
Which heading holds a reviewer: the decision, or the case for it
The heading that carries the decision is weighed against the sections around it — how long each one keeps a reviewer, and whether they loop back to the decision before commenting.
An example — not your document. Sections are the document’s own headings.
Most of their attention went to “Diagram” — 2m 35s 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 design doc has to do. For the blocks the editor is built from — see the editor.
That page is for the diagram a reader judges an architecture by. This one is for the decision itself — the alternatives, the reasoning, and the comments a reviewer leaves before it ships.
Not yet — start from a blank document; a decision set apart from its reasoning, alternatives kept next to the one that won, and resolvable comments all work from the first paragraph you write.