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
Use Cases
Frequently Asked Questions
From the Blog
How to Document Your Code Effectively
Effective code documentation explains the why, stays close to the code, and never lies. Learn what to document, what to skip, and how to keep docs from rotting.
Read More Career GrowthHow to Add Your Resume to LinkedIn
You can add your resume to LinkedIn either as a featured document on your profile or as an attachment when applying to a job post. This guide walks through both methods and explains when to use each one.
Read More Career GrowthResumes and Portfolios: What Each One Is Actually For
A resume exists to survive a fast screening pass; a portfolio exists to provide evidence once someone is already interested. Confusing the two produces resumes stuffed with detail nobody reads and portfolios that assume context the reader lacks. This article separates the jobs and shows where each document should stop.
Read More Cloud & CybersecurityNoSQL Data Models: Document, Key-Value, Wide-Column, Graph
The four NoSQL families each optimise for a different access pattern and each has query shapes that make it a poor choice. This guide explains what document, key-value, wide-column and graph stores are actually good at, how to model for them, and the failure modes that only appear once your data grows.
Read More