Romanticize Code on YouTube · Open on YouTube
Design docs, RFCs and ADRs · Proficient · Lesson 78 of 98 · 19 min video, then about 2 hours of practice
The anatomy of a good design doc
After this you can structure a design doc with context, goals and non-goals, the proposed design, alternatives considered, risks and an estimate.
Why it matters
Good design docs share a shape. Context and problem first, so a reader knows why this matters. Goals and non-goals, which prevent most scope arguments. The proposed design, at the level of detail needed to find problems. Alternatives considered, described fairly. Cross-cutting concerns: security, privacy, observability, migration and rollback. The alternatives section is where senior judgement shows. If the alternatives are straw men, reviewers will notice. Trap: so much detail that the design is lost. Put detail in appendices.
How to use this resource
A recent, practical walk through what makes design docs persuasive and how they are judged.
Go further
Go deeper