The design doc
Write it before you build it
Kai and Remy agree on Shard Garden in a chat. A week later, Kai is building a four-player garden and Remy is building an eight-player one. Both followed the chat.
A design doc is a document that says what the team will build and why, written before the big build. The team argues on paper, where a change costs minutes instead of weeks.
What goes in one
Malte Ubl's article "Design Docs at Google" lists the usual parts:
- Context and scopeThe situation today, and what we are building.
- Goals and non-goalsWhat it must do, and things that could be goals but we chose not to do.
- The designHow it works: an overview first, then details like data and APIs.
- Alternatives consideredOther ways to build it, and why we did not choose them.
- Cross-cutting concernsSecurity, privacy, and how we will see problems.
Quick check
Which line should Kai list as a non-goal for Shard Garden?
- Shard Garden will not have player-versus-player battles at launch
- Shard Garden must let four friends play together
- Shard Garden will crash less than once in 1,000 matches
Show the answer
Shard Garden will not have player-versus-player battles at launch
A non-goal is something that could reasonably be a goal, but the team chose not to do it. Battles are a fair idea, so naming them as a non-goal saves the argument later.
Alternatives considered
Ubl calls this one of the most important sections. Remy considers three ways to save gardens: on each player's device, on our own server, or in Firebase.
The doc lists each option's trade-offs, what you gain and what you give up, and explains why the chosen one fits Shard Garden's goals best. Reviewers can then argue about trade-offs, not opinions.
How long, and when to skip it
For a large project, Ubl puts the sweet spot at around 10 to 20 pages. A small change gets a "mini design doc" of 1 to 3 pages.
Sometimes the answer is no doc at all: when the solution is obvious, or when a quick prototype answers the question faster than writing would.
Quick check
Every change, even fixing a typo in a menu, needs a design doc first.
- True
- False
Show the answer
False
Ubl says to skip the doc when the right solution is not in doubt. Then the doc costs more than it saves.
Review reply
Section 3 says we run our own save servers. Why not Firebase?
Which section of the doc should already answer this?
- Alternatives considered
- Context and scope
- Cross-cutting concerns
Show the answer
Alternatives considered
Alternatives considered names the other options, like Firebase, and the trade-offs that made the team choose its own servers.
Reviewed, then built
The author shares the doc, teammates comment, the author answers and updates it, and then the building starts. The doc stays in the repo next to the code, so a new teammate can read why Shard Garden works the way it does.
Bolt says: Next: RFCs, the way big shared projects let anyone propose a change.
Fact-checked 12 October 2026
- Malte Ubl: Design Docs at Google industrialempathy.com