Why I write design docs before code
One page, three sections, and the arguments it saves a month later.
By the end of this post you should be able to reproduce the whole thing yourself in under an hour, including the parts I got wrong the first time — those are marked so you can skip them if you're in a hurry.
The problem
What surprised me most was how small the final change was. Most of the work was understanding the problem precisely enough that the fix became obvious, and that understanding took far longer than the fix itself.
The numbers below are from my own machine and my own workload. Treat them as a method, not a benchmark: the point is how the measurement was taken, not the exact figures it produced.
- Latency at p50, because most users live there
- A second point, kept short on purpose
First attempt
What surprised me most was how small the final change was. Most of the work was understanding the problem precisely enough that the fix became obvious, and that understanding took far longer than the fix itself.
By the end of this post you should be able to reproduce the whole thing yourself in under an hour, including the parts I got wrong the first time — those are marked so you can skip them if you're in a hurry.
Everything above is the short version. The full write-up of how this played out is a story for another day — for now, the takeaway is simple: one page, three sections, and the arguments it saves a month later is a decision you make once and revisit deliberately.