What is a design doc — and why engineers who skip them pay for it later.
Short answer
A design doc (engineering design document or technical design document) is a written description of how a software system or feature will be implemented. Where a PRD answers 'what and why,' a design doc answers 'how.' It documents the chosen technical approach, alternatives considered, trade-offs made, and the key risks. Written before implementation, reviewed by peers, and stored for future reference.
Design docs are a pre-implementation practice common at Google, Amazon, Stripe, and most mature engineering organizations. The investment — typically 4–8 hours to write a design doc — routinely saves days or weeks of implementation rework caused by architectural decisions made too late to change cheaply.
What a design doc is not. Not a spec (which describes product behavior for engineering to implement). Not an ADR (which documents a single architectural decision and its rationale). Not documentation written after the fact — design docs are prospective, written before implementation begins.
Standard sections.
Overview / TL;DR. A 3–5 sentence summary of what the system does, why it's being built, and the key architectural decision it makes. Someone who reads only this should understand the gist.
Background. The context: what problem are we solving, what constraints exist, what prior work is relevant? Links to the PRD, previous design decisions, or related systems.
Goals and non-goals. What this design achieves and what it explicitly does not address. Non-goals are as important as goals — they bound the problem.
Proposed design. The meat of the document: the architecture, the data model, the API surface, the component relationships. Use diagrams where they're clearer than prose (system diagrams, sequence diagrams, data flow). Be specific about technology choices: "we'll use Postgres with the jsonb column type" not "we'll use a database."
Alternatives considered. The 2–3 other approaches evaluated and why each was rejected. This is the section most often skipped and most valuable — it prevents future engineers from re-proposing alternatives that were already considered.
Implementation plan. How the work will be sequenced. What can be parallelized. Where the integration points are. Milestone breakdown if the feature is complex.
Security and privacy. How sensitive data is handled, access control design, and any compliance requirements.
Observability. What metrics, logs, and alerts will be added. How will on-call engineers know if this is failing in production?
Open questions. Known unknowns, with owners and resolution deadlines.
Review process. Share with peers before implementation. Collect comments async for 2–3 days, then a 30-minute review meeting. Incorporate feedback. The goal is to surface misalignments before they become code.
When the design is sketched at a whiteboard — system diagrams, component boundaries, data flows — snap the board with BoardSnap. The AI reads the architecture diagram and produces a structured design doc outline with the key components and relationships captured.
Frequently asked
How long should a design doc be?
2–6 pages for most features. A complex system with multiple components, significant data model changes, or cross-team dependencies might run to 10–15 pages with diagrams. The goal is to cover all sections that have meaningful design decisions — not to be exhaustive. If a section can be summarized in one sentence, don't pad it.
Who reviews a design doc?
Peer engineers who will implement adjacent systems, the tech lead or architect, the product manager (for alignment on behavior), and any team whose systems will be affected by integration points. Reviewers comment async, then a single review meeting resolves open questions. The author makes the final call on design decisions after incorporating feedback.
When should you skip the design doc?
For changes that are small (under a few days of engineering work), have no cross-team dependencies, and have an obvious implementation path. The test: would a peer engineer look at this and have significant questions about approach or trade-offs? If no — skip the doc. If yes — write it.
See it work in ten seconds.
BoardSnap is free on the App Store. Snap a board — get a summary and action plan.