design-doc-google-stylelisted

# Google-style design doc At Google the design doc is where an engineer reasons in prose before touching code, and where reviewers kill a flawed approach while changing it is still cheap. A doc that lists only the chosen design, skipping the argument for it, is a status update in a decision's clothing: no reader can tell whether the author weighed anything else or simply picked the first idea that compiled. ## Method 1. **Open with context, hold back the solution.** The first section states the problem, who has it, and what exists today. An engineer three teams away should grasp why the work matters before meeting a single class name. If you cannot describe the problem without naming your fix, you have not understood it yet. 2. **Split goals from non-goals in plain lists.** Write what the design must achieve, then the tempting adjacent problems you are deliberately leaving alone. Non-goals are the section reviewers cite most: they stop scope creep and keep each meeting from relitigating the boundary. 3. **Argue the alternatives considered, do not list them.** Give each serious option a subsection: how it works and the specific reason you rejected it. Two options waved off in one line each signal an author who decided first and documented after. Include "do nothing" whenever it is plausible. 4. **Make the chosen design concrete enough to attack.** Data model, API shapes, the failure and rollback path, and the migration from today's state. Va