Scrolls
8 min read
On this page

Why Design Docs Matter

A design document is not paperwork. It is a thinking tool disguised as a communication tool. The primary value of a design doc is not the artifact it produces — it is the thinking process it forces. Writing a design doc makes you confront ambiguity, surface assumptions, and resolve contradictions before they become bugs in production code.

Teams that skip design docs do not save time. They move the cost of unclear thinking from the document phase (where changes are cheap) to the implementation phase (where changes are expensive). A paragraph rewritten takes five minutes. A system rewritten takes five months.

Writing Forces Clarity

You think you understand the system you are about to build. Then you sit down to write the design doc and discover you do not.

This is not a failure. This is the entire point. The act of writing forces a level of precision that mental reasoning alone does not demand. In your head, you can gloss over details, wave away edge cases, and hold contradictory assumptions simultaneously without noticing. On paper, you cannot.

In your head:
"The service will process events from the queue and update
the database."

On paper, you have to answer:
- Which queue? Kafka? SQS? RabbitMQ?
- What's the message format?
- What happens if processing fails? Retry? Dead letter?
- What if the same event arrives twice?
- What's the expected throughput?
- What's the latency requirement?
- What happens during a database outage?
- Is ordering guaranteed? Does it need to be?
- What's the deployment strategy? Can we deploy independently
  of the producer?

Every one of these questions represents a decision that will get made one way or another. Without a design doc, those decisions get made implicitly during implementation — by whichever engineer happens to write that piece of code, based on whatever they happen to assume at the time. With a design doc, those decisions get made explicitly and reviewed by the team.

Implicit decisions are the leading cause of system integration failures. Engineer A assumes eventual consistency. Engineer B assumes strong consistency. Neither writes it down. They discover the mismatch three weeks into implementation when things break in a way neither of them expected.

Cheap to Change a Doc, Expensive to Rewrite Code

The cost of changing direction scales with how much you have built. A change during design costs almost nothing — you rewrite a paragraph, update a diagram reference, and move on. The same change during implementation costs days or weeks. After launch, it can cost months.

Cost of change at each phase:

Design doc phase:
  "Let's use PostgreSQL instead of DynamoDB."
  Cost: Rewrite two paragraphs. Time: 30 minutes.

Implementation phase:
  "Let's use PostgreSQL instead of DynamoDB."
  Cost: Rewrite the data layer, change the schema, update
  the infrastructure code, re-run load tests.
  Time: 2-3 weeks.

Post-launch phase:
  "Let's use PostgreSQL instead of DynamoDB."
  Cost: Everything above, plus data migration, backwards
  compatibility, rollback planning, customer communication.
  Time: 2-3 months.

Design docs are cheap insurance. You invest a few days of writing and review to avoid months of rework. The return on investment is enormous, but the returns are invisible — they manifest as problems that never happened. This invisibility is why teams undervalue design docs. You never see the bug that the design review caught, the architecture mistake that got corrected in a paragraph instead of a sprint, the misalignment that surfaced in comments instead of in a production incident.

Surfacing Disagreements Early

A design doc is a magnet for disagreement — and that is a feature, not a bug. When you publish a design doc for review, you are inviting the team to challenge your assumptions, question your decisions, and propose alternatives. This is uncomfortable. It is also vastly preferable to discovering disagreements during implementation.

Without a design doc:
Week 1: Engineer starts building service with REST API.
Week 3: Senior engineer reviews PR: "Why isn't this gRPC?
         We agreed all internal services use gRPC."
Week 3: Debate ensues. Half the team prefers REST for this
         use case. Half prefers gRPC for consistency.
Week 4: Decision finally made. Two weeks of code reworked.

With a design doc:
Day 1: Engineer writes doc proposing REST API with rationale.
Day 3: Senior engineer comments: "Have you considered gRPC?
        Our standard is gRPC for internal services."
Day 3: Engineer responds with trade-off analysis in the doc.
Day 4: Team discusses, decides, and documents the decision.
Day 5: Engineer starts building with the agreed approach.

The disagreement existed in both scenarios. The design doc surfaced it in days instead of weeks, and at the cost of a few comments instead of a code rewrite.

Design docs also surface a specific kind of disagreement that meetings cannot: the disagreement from the person who was not in the room. A meeting captures the opinions of attendees. A design doc circulates to the whole team — including the person on vacation, the person in a different timezone, and the person who is shy in meetings but has critical domain knowledge.

Design Docs as Institutional Memory

Code tells you what the system does. It does not tell you why it does it that way. Six months from now, a new engineer will look at your system and ask: "Why did they use eventual consistency here? Why not strong consistency?" The code cannot answer that question. The design doc can.

From the code:
async function processEvent(event) {
  await cache.set(event.id, event.data, { ttl: 300 });
  await queue.publish('events.processed', event.id);
}

This tells you: events are cached for 5 minutes, then a
message is published to a queue.

From the design doc:
"We chose eventual consistency with a 5-minute cache TTL as a
compromise between data freshness and database load. Strong
consistency would require a synchronous database write on every
event, which at our projected 10K events/second would exceed
the database's write capacity. The 5-minute window means
downstream consumers may see stale data, but the business
stakeholders confirmed this is acceptable for all current
use cases (see discussion in comment thread, 2024-03-15)."

This tells you: why 5 minutes, what was rejected, who agreed.

Design docs turn transient knowledge — the reasoning that lived in people's heads during design discussions — into permanent artifacts. People leave teams. Memories fade. Documents persist.

When to Write a Design Doc

Not every change needs a design doc. Writing a design doc for a one-line config change is waste. Writing a design doc for a new microservice is essential. The boundary is judgment, but here are useful heuristics:

Write a design doc when:

  • The project will take more than one engineer-week of effort
  • The change affects more than one team or service
  • The decision is difficult to reverse once implemented
  • There are multiple viable approaches and the trade-offs are not obvious
  • The system has significant operational implications (data migration, downtime, performance impact)
  • You find yourself explaining the same design decision to multiple people

Skip the design doc when:

  • The change is well-understood and straightforward
  • The implementation is easily reversible
  • The scope is small and contained to one component
  • There is an existing pattern you are following without deviation
Needs a design doc:
- New service architecture
- Database migration strategy
- Major API redesign
- New authentication system
- Cross-team data pipeline

Probably does not need a design doc:
- Adding a new REST endpoint following existing patterns
- Upgrading a library version
- Fixing a bug with a clear root cause
- Adding a feature flag
- Writing a new unit test

When in doubt, write a short design doc. A two-page doc that took an hour to write can save days of misalignment. A missing design doc that should have existed will cost far more.

The Design Doc Is Not the Design

A common misconception: the design doc is the deliverable. It is not. The design doc is a tool for reaching a good design. The real deliverables are the decisions it produces and the alignment it creates.

This distinction matters because it changes how you approach the document:

  • Perfecting the prose is less important than surfacing the right questions
  • Getting feedback is more important than getting the formatting right
  • A design doc with messy writing but good decisions is better than a polished document with unexamined assumptions
  • The comments and discussion on the design doc are as valuable as the document itself

Some of the most valuable design docs are the ones that got significantly rewritten during review. That rewriting means the review process worked — it challenged assumptions, improved decisions, and built shared understanding.

Signs your design doc process is working:
- Reviewers ask hard questions you hadn't considered
- The final design differs meaningfully from the first draft
- Reviewers from other teams flag integration issues
- The doc captures rejected alternatives and the reasons

Signs your design doc process is broken:
- Docs are rubber-stamped without substantive feedback
- The design never changes based on review
- Only the author's team reviews the doc
- Docs are written after implementation (to check a box)

Building the Habit

Writing design docs consistently requires organizational habit, not just individual discipline. Teams that write design docs successfully have a few things in common:

  • There is a lightweight template that reduces the activation energy of starting
  • There is a clear expectation about when a design doc is needed
  • There is a review process that people actually participate in
  • Design docs are stored somewhere findable, not lost in email threads
  • The team references past design docs when making related decisions

The biggest barrier is the first one: starting. A blank page is intimidating. A template with section headings and prompting questions makes it less so. You do not need an elaborate template — a simple list of sections (Context, Problem, Proposed Solution, Alternatives, Risks) is enough.

Common Pitfalls

Writing the design doc after building the system. A design doc written retroactively is documentation, not design. It has value as a record, but it misses the primary benefit: forcing clear thinking before implementation. If you find yourself writing design docs to justify decisions already made, the process has gone wrong.

Treating the design doc as a spec. A design doc describes the approach, the trade-offs, and the key decisions. It is not a line-by-line specification. Implementation details that do not affect the design should stay in the code. Overloading the design doc with implementation minutiae makes it too long to review effectively.

Not revisiting the design doc after implementation. The design will change during implementation — it always does. Update the doc with a brief "Implementation Notes" section that captures what changed and why. This keeps the doc useful as a reference rather than a misleading historical artifact.

Requiring consensus before proceeding. Design review should surface objections, not block progress indefinitely. Set a review deadline. Address substantive concerns. Then decide and move forward. Waiting for unanimous agreement means waiting forever.

Making the design doc too formal. A design doc that requires weeks of polish will not get written. A rough document that captures the key decisions in a few pages is infinitely more valuable than a perfect document that never gets started. Lower the bar for "good enough" and raise the bar for "must be written."

Key Takeaways

  • A design doc is primarily a thinking tool. The act of writing forces clarity that mental reasoning alone cannot achieve.
  • Changes are cheapest during the design phase. A paragraph rewrite costs minutes. A code rewrite costs weeks. A production rewrite costs months.
  • Design docs surface disagreements early, when they can be resolved through discussion instead of code rework.
  • Design docs serve as institutional memory, capturing not just what was decided but why — information that code alone cannot preserve.
  • Write a design doc when the project is complex, cross-team, hard to reverse, or has multiple viable approaches. Skip it for straightforward, small, reversible changes.
  • The document is not the deliverable. The decisions, alignment, and shared understanding it produces are the deliverables.