When to write a design doc

A Slack thread buries the decision under twenty replies. A whiteboard dies when someone erases it. A design doc is the short written proposal that names the problem, the options, and the trade-offs before you invent months of code that solves the wrong thing.

The point is not bureaucracy. Unstructured prose is cheaper to change than code, easier for people outside your team to critique, and a record of why you chose A over B when that choice looks arbitrary later.

The big idea

Companies call these design docs, tech specs, RFCs, or ERDs. The name matters less than the habit.

Three jobs, in order:

1. Catch problems while they are cheap. Writing exposes gaps conversation hides: missing non-goals, an impossible latency budget, a dependency nobody owns.
2. Align stakeholders. Security, privacy, and neighboring teams can comment without sitting in your standup.
3. Leave a record. Future you needs the decision and the rejected alternatives, not a git archaeology project.

Walking through the size decision

Match the cost of writing to the cost of getting it wrong.

Skip the doc when the change is localized, reversible, and already understood by the people who will review the PR — a bug fix, a small API tweak inside one service, a refactor with characterization tests.

Write one when the blast radius is large, the approach is ambiguous, or you need buy-in from people who will not read every line of the diff.

A week of debate on a reversible config change is waste. Zero writing before a six-month migration is negligence.

Common mistakes

• Doc as theater. Written after the code ships "for process." Useless. Write before the expensive work.
• No non-goals. Scope expands until the project never ships.
• Treating every ticket as an RFC. Process is a tool. Over-documenting small work trains people to ignore docs.

Check yourself

A teammate wants a six-month datastore migration with no written design. What do you do?

Write a design doc. The blast radius is large and the approach is not obvious.

You are renaming a field inside one service. Do you need an RFC?

No. A one-pager or just the PR is enough if the reviewers already understand the change.

Key takeaways

• A design doc catches wrong approaches while changes are still cheap and leaves a record of why.
• RFCs propose; ADRs record. Use both. Neither is a religion.
• Right-size: skip tiny reversible work; write a fuller RFC for cross-team or multi-week bets.
• Draft where comments are easy; store the approved decision next to the code.

Further learning

Next, the sections reviewers actually need: the design doc template.

Design Docs at Google (Malte Ubl)One of the key elements of Googleindustrialempathy.com