Design docs and RFCs

A whiteboard conversation dies when someone erases the board. A Slack thread buries the decision under twenty replies. A design doc is the durable artifact: a short written proposal that forces you to name the problem, the options, and the trade-offs before you invent six months of code that solves the wrong thing.

Malte Ubl's description of how Google uses them is still the clearest: the point is not bureaucracy. Unstructured prose is often a better tool than code early in a project — cheaper to change, easier for experts outside your team to critique, and a record of why you chose A over B. Companies call these design docs, tech specs, RFCs, or ERDs; the name matters less than the habit.

If you are aiming for SDE2 and beyond, this is leverage. Owning a feature end to end means you can get alignment without waiting for someone else to "design it." A strong doc also lets a staff engineer review your approach in twenty minutes instead of pairing for an afternoon.

Concepts in this section

Read them in order. Each one builds on the one before.

Step	Concept	What it answers
1	When to write a design doc	Skip, one-pager, RFC, or ADR?
2	Design doc template	Which sections do reviewers need?
3	Writing for reviewers	How do you lead with the decision?
4	Running a design review	Who comments, when do you meet, what gets recorded?

The design names what and why. Estimation and planning names when and in what order. Written communication is the delivery vehicle for both.

A burst of review, worked out

Google-style design docs for major projects often land around 10–20 pages; incremental work uses mini docs of a few pages. Match the cost of writing and reviewing to the cost of getting it wrong.

A staff engineer can review a tight doc in about twenty minutes. That same design in an afternoon pairing session costs two people several hours. The doc is how your name attaches to a decision the org can still find next year.

Common mistakes

Doc as theater. Written after the code ships "for process." Write before the expensive work.
No non-goals. Scope expands until the project never ships.
No alternatives. Reviewers smell advocacy and dig in harder.
Unresolved comments. Shipping while threads are red means you did not actually decide.
Orphan docs. Approved design with no link from the epic or ADR index.

Key takeaways

Design docs catch wrong approaches while changes are still cheap and leave a record of why.
Lead with the decision; support it with diagrams, numbers, goals/non-goals, and real alternatives.
Right-size the artifact: ADR or one-pager for small reversible choices; fuller RFC for cross-team or multi-week work.
Review async first; meet to resolve; record decisions so code review does not re-litigate them.