Design Document

Design Document

Overview

A design document is the bridge between "what we're building" (Working Backwards output) and "how we're building it." It forces the author to think deeply before writing code, surface trade-offs explicitly, consider operational reality, and invite scrutiny from peers. The document is not documentation—it is a thinking tool. If writing the design document doesn't change your approach at least once, you didn't think deeply enough.

A good design document answers: What problem are we solving? Why this approach over alternatives? What are we trading away? How will we know it's working? How will we operate it at scale?

When to Use

• Before starting implementation of any project estimated at more than 2 engineer-weeks
• When introducing a new service, API, or significant data store
• When making architectural changes that affect other teams
• When changing system boundaries (splitting or merging services)
• When the blast radius of failure includes customer-facing impact
• When multiple valid approaches exist and the choice isn't obvious
• Before any project that will require a Design Bar Raiser review

Amazon Context

At Amazon, writing is thinking. A design document is a 6-page narrative (not PowerPoint) that forces clarity of thought. The design document ties directly to the Working Backwards process: the PR/FAQ and PRFAQ define what and why for customers; the design document defines how for engineers. The Design Bar Raiser (DBR) review process ensures the document meets a high bar before implementation begins.

Design documents are living artifacts during the design phase but become historical records once approved. They capture the reasoning at a point in time—including constraints, assumptions, and rejected alternatives—so future engineers can understand why decisions were made, not just what was decided.

The standard flow: Working Backwards → Design Document → Design Bar Raiser Review → Implementation Plan → Code.