The most expensive bugs are the ones baked into a design before anyone writes a line of code, the wrong architecture, the missed dependency, the edge case nobody considered. By the time they show up in the running system, they're costly to fix. Writing a short design doc before building catches many of them while they're still cheap: words on a page you can change in an edit.
Key Takeaways
- Google writes a design doc before significant projects, covering motivation, design, alternatives, and trade-offs (Design Docs at Google).
- Writing first surfaces edge cases and dependencies early, when they're cheap to fix (Design Docs at Google).
- Circulating a doc aligns teams and prevents "I thought we agreed" surprises (Pragmatic Engineer).
- Engineers who write design docs and get them reviewed tend to ship more maintainable architecture.
Why Writing First Works
A design doc (also called an RFC, request for comment) is a short document describing what you're about to build and why, before you build it. The value comes from a simple fact: thinking is cheap on paper and expensive in code. Writing forces a clarity that hand-waving in a meeting hides. When you have to spell out the approach, the gaps become obvious, the edge cases surface, and the hidden dependencies show up (Design Docs at Google). Catching a design flaw in a document is an edit; catching it after it's built into the system is a rewrite.
Google's own engineers draw a neat parallel: engineers who write tests and ask for code reviews ship more maintainable code, and engineers who write design docs and ask for reviews ship more maintainable architecture (Design Docs at Google). Review works at the design level for the same reason it works at the code level, a second set of eyes catches what the author can't see.
What a Design Doc Prevents
Beyond catching technical flaws, a circulated design doc aligns people before work starts. It surfaces disagreement early, when changing course is free, instead of at the end in a painful "wait, I thought we agreed" moment (Pragmatic Engineer on RFCs). Other teams spot conflicts with their systems, dependencies get discovered before they block anyone, and the decision, with its trade-offs and the alternatives considered, gets written down for everyone who joins later.
| Without a design doc | With a design doc |
|---|---|
| Flaws found after building | Flaws found while it's still words |
| Alignment assumed, then broken | Disagreement surfaced early |
| Dependencies discovered late | Dependencies mapped up front |
| Decisions live in one head | Trade-offs written down |
A Concrete Version
An engineer is about to build a new notification system and writes a one-page design doc first. In writing it, they realize the approach would double-send during a specific retry, an edge case that would have been an ugly production bug. They fix it in the doc in five minutes. A teammate reviewing the doc points out it collides with a change the platform team is making, a dependency nobody would have caught until integration. Two significant problems, both solved before a single line was written, for the cost of an hour of writing and reading.
The Honest Counterpoint
Design docs have a failure mode: bureaucracy. Not every change needs one. Forcing a formal doc for a trivial fix is waste and slows people down, and a doc written to be filed rather than read helps no one. The point is proportionality: write a design doc for the significant, hard-to-reverse, cross-team decisions where thinking-before-building pays off, and skip it for the small stuff. A short doc for a big decision, no doc for a small one.
What This Means for Distributed Teams
Design docs are especially valuable on distributed teams, where you can't gather at a whiteboard, and where a written, async proposal is how a decision gets made and reviewed across time zones. They're part of the same documentation and async-first discipline that makes remote teams work, and writing clearly is a core skill we look for, because on a distributed team, clear writing is how good thinking travels. See available engineers.
Frequently Asked Questions
What is a design doc or RFC?
A short document describing what you plan to build and why, before you build it, covering the motivation, the design, alternatives considered, and trade-offs. Teams circulate it for review, like a code review for architecture.
Why write a design doc before coding?
Because flaws are cheap to fix on paper and expensive to fix in a built system. Writing surfaces edge cases, hidden dependencies, and disagreements early, when changing course is free.
Does every change need a design doc?
No. Reserve them for significant, hard-to-reverse, or cross-team decisions. Forcing a formal doc for trivial changes is bureaucracy that slows people down.
How do design docs help remote teams?
They let decisions get proposed and reviewed asynchronously across time zones, without a whiteboard. A written proposal is how good thinking travels on a distributed team.
The Bottom Line
The cheapest place to catch a design flaw is in a document, before it's built into the system. Google writes a design doc before significant projects because writing forces clarity, surfaces edge cases and dependencies, and aligns teams while course-correction is still free. Write a short doc for the big decisions, get it reviewed, and skip it for the small stuff.
Roberto Espinoza is CEO of Ruzora, which helps US startups hire pre-vetted senior LATAM engineers in 72 hours. See available engineers.
