Part 0 · 2 chapters · ~12 min

Design Docs and RFCs

When a design doc is worth writing, the sections and the reader question each answers, writing the problem with evidence, goals and non-goals, presenting options fairly with costs, diagrams that clarify, rollout and rollback plans, open questions with owners, length and the one-page summary, and a before-and-after rewrite.

A template that forces the hard parts

code

# Design: Real-time payout status via webhooks
Author · Reviewers (security, ledger, mobile) · Status: draft · Decision by: 14 Nov

## Summary (5 lines)       What we will build, why, what it costs, what we need from readers.
## Problem                 Polling 5 rails every 30 s costs $2.1k/month; customers see stale status for up to 30 s;
                           support logs 410 "is my transfer done?" tickets/week.
## Goals / Non-goals       Goal: status within 5 s for 3 webhook-capable rails. Non-goal: changing the payout state machine.
## Options                 A) poll faster ($6k/month, still 10 s)  B) webhooks + fallback poll  C) webhooks only (misses lost events)
## Proposal                B. Signed webhooks into an inbox table; reconciliation job catches gaps.
## Risks                   forged webhooks → HMAC + IP allow-list · missed webhooks → fallback poll every 5 min
## Rollout                 one rail behind a flag; compare webhook vs polled status 2 weeks; then the rest
## Open questions          raw payload retention period? (owner: DPO, by 10 Nov)

THE SHAPE OF A DESIGN DOC

each section answers a reader's question

swipe the figure sideways, or tap expand for full screen

1/4

problem first

Readers must agree on the problem before they can judge a solution. State it with evidence: numbers, incidents, user reports.

evidence before ideasnumbers, incidents, users

Before and after

before	after
"We should move to an event-driven architecture to improve scalability and decouple our services."	"Payout status reaches customers up to 30 s late and costs $2.1k/month in polling. Webhooks from three rails would cut that to under 5 s and $300/month."
"There are some risks around security."	"A forged webhook could mark an unpaid payout as complete. We verify an HMAC signature and only accept the rails' published IP ranges."
"We will roll out carefully."	"Rail 1 only, behind flag payout_webhooks, for two weeks, comparing webhook and polled status; rollback is turning the flag off."

The rewrite rule is the same each time: replace an abstract claim with the specific number, mechanism or step it stands for. If you cannot, you have found a gap in the design, not in the writing.