Design Document Structure — Language Guide
Standard sections, non-goals, open questions, implementation divergence, and background writing
Design document structure essentials
- Sections: Background → Goals → Non-goals → Proposed Design → Alternatives Considered → Open Questions
- Non-goals: specific exclusion + cross-reference + reason — prevents scope creep and "have you considered X?" questions
- Open Questions: secondary decisions only — foundational questions must be resolved before the doc is published
- Divergence disclaimer: design docs are planning artefacts, not current-state documentation
- Background: current state with numbers + the problem + what this document addresses
Question 0 of 5
What are the standard sections of a Design Document, in the correct order?
Background → Goals → Non-goals → Proposed Design → Alternatives Considered → Open Questions. Standard Design Doc section purposes:
- Background: why this work is happening — the context a new reader needs to understand the document
- Goals: what success looks like — specific, measurable where possible
- Non-goals: what this design explicitly does NOT address — prevents scope creep and "have you thought about..." questions
- Proposed Design: the main body — how the solution works
- Alternatives Considered: what else was evaluated and why it was rejected
- Open Questions: unresolved issues that the design depends on — flagged so reviewers know what still needs answering
Which Non-goals section is written most effectively?
Non-goals need specificity + cross-reference + reason for exclusion. Non-goals writing formula:
- Specific exclusion: "multi-region failover" not "everything" — must be specific enough that a reviewer can tell whether their concern is in scope
- Cross-reference: "see RFC-0056" — tells readers where to go if they care about the excluded topic
- Reason: "deferred to Phase 2", "covered separately by" — explains why, not just what
- Without explicit non-goals, reviewers will raise out-of-scope concerns as blocking issues
- "Have you considered X?" questions are pre-empted by "We considered X; it's a non-goal because Y"
- Non-goals also protect the team from scope creep during implementation — "that's a non-goal, it goes on the Phase 2 backlog"
A Design Doc's Open Questions section contains: "Q: Should we use PostgreSQL or MySQL?" This is an open question. Why is this problematic at the Design Doc stage?
Open Questions should be secondary decisions, not foundational ones — foundational questions block the design. Open Questions classification:
- Valid open question: "Q: What should the default cache TTL be — 5 minutes or 15 minutes? This doesn't affect the design architecture, just the configuration." — secondary, doesn't block design
- Invalid open question (foundational): "Q: Should we use PostgreSQL or MySQL?" — the entire schema, query patterns, and replication strategy depend on this answer; the design cannot be written without it
- Resolve them before publishing the design doc
- If they can't be resolved quickly, write an RFC or hold a design meeting first
- Mark the doc clearly as "Draft — pending resolution of [question]"
A Design Doc contains the sentence: "This document reflects the design as of May 2026; implementation may diverge." Why is this statement important?
Design docs are planning artefacts — they reflect intent at a point in time, not the current implementation. Why this disclaimer matters:
- Design docs are written before implementation; reality always deviates somewhat — unexpected complexity, discovered constraints, better approaches found during coding
- Without the disclaimer, a reader may mistake a 2-year-old design doc for accurate documentation of the current system
- It invites the reader to verify: "check the current implementation or the updated design doc at [link]"
- Keep design docs as-is (they're historical artefacts that explain the intent)
- Add a "Status: Implemented — see [link] for notes on what diverged" section at the top
- Or link from the design doc to the ADR that captures the decision to deviate
Which sentence is written in the correct style for a Design Doc's Background section?
Background = current state with specific numbers + the problem that makes change necessary + what this document addresses. Background section formula:
- Current state: "50K transactions/day synchronously" — specific, not vague
- The problem: "at 10× volume this will exhaust our thread pool" — the constraint that makes the status quo unacceptable
- Projection: "500K/day by Q4" — explains why this is urgent now, not in 2 years
- Bridge to this doc: "This design describes how we will move to async processing" — tells the reader what the document is for