Design doc
dih-ZINE dok
A technical document that describes how a system or feature will be built before implementation begins.
A design doc is a written plan for how you are going to build something. It describes the architecture, the data model, the API contracts, the trade-offs, and the milestones. You write it before writing code. It is the blueprint.
Google popularized the practice. Every significant project at Google starts with a design doc. The doc goes through review by peers and senior engineers. Feedback is given in comments. The design evolves before a single line of code is written. This catches architectural mistakes when they are cheap to fix, not after three months of implementation.
A good design doc is not a specification. It does not describe every function signature or database index. It describes the shape of the solution, the key decisions, and the reasoning behind them. It answers "why this approach?" not just "what will we build?" The best design docs include diagrams, sequence flows, and concrete examples.
Examples
A team designs a notification system.
The design doc outlines three approaches: polling, webhooks, and server-sent events. It evaluates each against requirements (real-time delivery, mobile support, cost at 1M users). The doc recommends webhooks for reliability and SSE for real-time display. A senior engineer's review catches that the proposed schema will not scale beyond 10M notifications per day. The schema is redesigned before implementation.
A startup documents its authentication architecture.
The design doc specifies JWT-based authentication with refresh tokens, describes the token lifecycle, maps out the login flow with sequence diagrams, and lists security considerations. When a new engineer joins six months later, the design doc explains why the team chose JWTs over session cookies and why refresh tokens rotate on use.
An infrastructure team plans a multi-region deployment.
The design doc covers data replication strategy (async with conflict resolution), DNS-based routing, failover procedures, and cost projections. The cost section shows that the third region adds $15,000/month but reduces latency for APAC users from 400ms to 80ms. Leadership approves the investment based on the documented trade-offs.
In practice
Design document template
DESIGN DOCUMENT: [Feature/System Name] Author: [Name] | Date: [DATE] | Status: [Draft/Review/Approved] OVERVIEW [What are we building and why? 2-3 sentences.] GOALS AND NON-GOALS Goals: - [What this design must achieve] Non-goals: - [What is explicitly out of scope] BACKGROUND [Context the reader needs. Link to related docs, RFCs, or prior art.] DESIGN [The meat of the document. Architecture, data model, API contracts, sequence diagrams.] SECURITY AND PRIVACY [How does this handle auth, PII, encryption, access control?] TESTING PLAN [How will you verify this works? Unit tests, integration tests, load tests?] METRICS AND MONITORING [What will you measure to know this is working in production?] TIMELINE | Milestone | Target date | Owner | |-----------|-------------|-------| | [Phase 1] | [Date] | [Name]|
Read more on the blog
Frequently asked questions
What is the difference between a design doc and an RFC?
An RFC proposes a change and asks for feedback on whether to do it. A design doc describes how to implement something that has already been approved. In practice, many teams blend them: the design doc includes both the proposal and the implementation plan. The distinction matters more in large organizations where decision-making and implementation are separate processes.
When is a design doc overkill?
For changes that are small, well-understood, and easily reversible. A bug fix does not need a design doc. Adding a field to an API might not either. A good rule of thumb: if the implementation will take less than a week and affects only one team, a detailed PR description is probably sufficient. If it takes more than a week or crosses team boundaries, write a design doc.
Related terms
A Request for Comments document that proposes a technical change and invites structured feedback from the team.
An Architecture Decision Record that documents a significant technical decision and its reasoning.
The gradual, uncontrolled expansion of a project's requirements beyond the original plan.
The structure and organization of a database, defining tables, columns, types, and relationships.
Application programming interface: a defined way for software programs to communicate with each other.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.