Design Document
A written proposal that explains how a system or feature will be built before the work begins
A design document (often called a design doc or RFC) is a written proposal that describes the problem, proposed solution, and trade-offs for a software system or feature before implementation starts.
Definition
A design document (often called a design doc or RFC) is a written proposal that describes the problem, proposed solution, and trade-offs for a software system or feature before implementation starts.
Overview
A design document exists to move the hardest thinking about a piece of software — its goals, constraints, and trade-offs — earlier in the process, onto a page that colleagues can read, question, and improve before code gets written. Typical sections include a problem statement or motivation, the proposed approach, alternatives that were considered and rejected, a description of the system's architecture (often with diagrams), and explicit callouts of risks, non-goals, and open questions that still need resolving. The practice was popularized inside large engineering organizations such as Google and Amazon, where the cost of building the wrong thing at scale is high enough that an hour of collective review is far cheaper than weeks of rework. Amazon's variant, the "six-pager," replaces slide decks with prose narratives read silently at the start of a meeting, on the theory that full sentences force clearer thinking than bullet points. A good design document is not documentation of a finished system — it is a decision-making tool for a system that doesn't exist yet. It's typically shared with a small group of reviewers (senior engineers, the tech lead, sometimes security or SRE stakeholders), who leave comments inline, and the author revises until concerns are resolved or explicitly accepted as trade-offs. Once approved, the document becomes a historical record of why the system was built the way it was, which is invaluable months later when someone asks "why did we do it this way?" Design documents scale with the size of the decision: a two-day feature might get a half-page doc, while a new service or a breaking API change might warrant several pages with a formal review meeting. Teams that skip this step for consequential changes often pay for it later in the form of costly rewrites, misaligned expectations between teams, or architecture that nobody can fully explain.
Key Concepts
- Problem statement and motivation section explaining why the work matters
- Proposed solution with architecture diagrams or data flow descriptions
- Explicit list of alternatives considered and why they were rejected
- Non-goals section clarifying what the design intentionally does not solve
- Risk and trade-off analysis, including performance, cost, and security implications
- Open questions section for unresolved decisions needing reviewer input
- Structured review process with named reviewers and approval status
- Living historical record referenced long after the feature ships