Template Design Doc

Engineering design docs: how to describe how

An engineering design document (also "tech spec" or "design doc") describes how a non-trivial change will be built. If the PRD says what and why, the design doc says how — and, importantly, why this how and not another. The format was popularized inside Google, where every senior engineer is expected to write and review design docs as part of their craft. The wider industry picked it up through public writing from Will Larson (Staff Engineer) and Camille Fournier (The Manager's Path), and through blogs at Stripe, GitHub and Twitter.

A typical design doc contains: context (where the system stands today), goals and non-goals, proposed design (architecture, data model, APIs, sequence diagrams), alternatives considered with explicit trade-offs, migration plan for legacy data and traffic, rollback strategy if the change blows up in production, open questions, and an approval list of reviewers whose sign-off is required. Length varies between three and ten pages for typical features and can run much longer for foundational projects.

PRD vs design doc vs ADR vs RFC

The four formats overlap and people confuse them. PRD targets stakeholders and answers what/why. Design doc targets engineers and answers how. RFC (Request for Comments) is a proposal stage: invites debate before consensus. ADR (Architecture Decision Record) is a single-decision artifact — short, immutable, captures the context, decision and consequences of one choice. Many teams use RFC for proposal, design doc for the approved plan, and ADRs as the historical record of the decisions inside it.

Review culture and the role of the tech lead

The tech lead usually drafts the design doc, but the value is the review process. Distributed teams review asynchronously via comments in the document; a meeting only happens if the comments deadlock. Etsy popularized blameless post-mortems as the companion pattern: when an outage happens, you reread the design doc to see what assumption broke. Visual notation often uses the C4 model (Simon Brown — Context, Container, Component, Code) for layered architecture diagrams.

Anti-patterns to avoid

Solution-first docs (no problem statement), no alternatives explored (the reader cannot judge the choice), no trade-offs (every decision is presented as obviously correct), no migration plan (operational impact ignored), no rollback (no plan B), and the "wall of text" doc with no diagrams. Tools: Google Docs (legacy), Notion, Confluence, GitHub wiki, dedicated ADR logs like adr-tools. ThoughtWorks publishes the Tech Radar as a complementary practice for tracking which technologies a doc can safely assume.

FAQ

When is a design doc mandatory? For any non-trivial change — new service, new data store, breaking API change, security-sensitive code, anything that crosses team boundaries. Routine refactors and bug fixes do not need one.

How is a design doc different from an ADR? An ADR records one decision, immutable, usually one page. A design doc bundles many decisions and evolves until the project ships. A design doc may produce several ADRs as its byproducts.

How long should it be? Three to ten pages for typical features. Longer for foundational projects. If you are above twenty pages, split into one main doc plus appendices.

Who has to approve it? The reviewers your team's culture defines — usually the tech lead plus one or two senior engineers from neighbouring teams whose systems you touch. Operational reviewers (SRE, security) join when relevant.