Design document template for engineers who hate writing docs

Most engineers don't hate writing. They hate writing something nobody reads. A design doc earns its time when it gets a decision made before code is written, and when someone six months later can open it and learn why the system looks the way it does.

This post gives you a design document template with four core parts, notes on what goes in each, and dense paragraphs from real docs reworked so a reader can skim them in a meeting.

When you need one

Skip the doc for small changes. Write one when any of these is true.

• The work will take more than a couple of weeks.
• More than one team has to change something.
• You're choosing between options that are hard to reverse, like a database or a public API shape.
• You expect someone to ask "why did we build it like this" next year.

The template

# <Project name> design

Author: <name>    Reviewers: <names>    Status: Draft | In review | Decided
Last updated: <date>

## Context
What exists today and what problem we're solving. Link data or tickets.

## Goals and non-goals
Goals: what must be true when this ships.
Non-goals: what we are deliberately not solving here.

## Options considered
### Option A: <name>
How it works, cost, risks.
### Option B: <name>
How it works, cost, risks.

## Decision
Which option, why, and what would make us revisit it.

## Rollout and open questions
Phases, flags, migration steps, and anything still unknown.

Context, goals, options and decision carry the weight. The last section keeps the doc honest about what isn't settled.

What goes in each part

Context. Two or three short paragraphs. Assume the reader knows the company but not this corner of the codebase. Include one number that shows the problem is real, like a p95 latency or a weekly count of failed jobs.

Goals and non-goals. Goals should be checkable after launch. "Faster search" isn't checkable. "Search results under 300 ms at p95 for accounts with a million records" is. Non-goals stop scope creep before the review starts. If you write "we won't support offline mode in this version," nobody spends the meeting debating it.

Options considered. List at least two real options, and one of them can be "do nothing." Give each the same headings so they compare side by side. Reviewers trust a doc more when the losing option is described fairly.

Decision. State it in the first sentence of the section. Then give the reason in two or three lines. Add what would change your mind, since that's the part future readers need most.

Dense paragraphs, reworked for skimming

Design docs go wrong at the paragraph level. Here are three examples with the product names changed.

Dense.

Currently the notification service, which was originally built for email only and later extended to support push and SMS through a series of adapters that share a common retry queue, experiences significant delays during peak periods because the retry queue is processed by a single worker and failed SMS sends, which are retried up to five times with backoff, block email and push messages behind them.

Reworked.

The notification service sends email, push and SMS through one shared retry queue. A single worker drains that queue. When SMS sends fail, they retry up to five times, and every email and push message waits behind them. At peak, that adds minutes of delay.

One sentence became four. Each one holds a single fact, and the last one states the cost.

Dense.

Option B would involve migrating to a managed queue which would reduce operational overhead though it might increase cost and there are some concerns around vendor lock in that were raised by the platform team but these may be acceptable given the timeline.

Reworked.

Option B moves us to a managed queue. Pros. Less to operate, built in dead letter handling. Cons. Roughly 20 percent higher monthly cost. The platform team flagged lock in. Verdict. Acceptable for this project if we keep our own message format.

Hedged clauses turn into short labeled lines a reader can scan in a review meeting.

Dense.

We decided after considerable discussion with multiple stakeholders to proceed with the approach outlined in Option A for the reasons described above.

Reworked.

We chose Option A, separate queues per channel. It fixes the head of line blocking with the smallest change to existing code. We'll revisit if SMS volume grows past ten times today's level.

"For the reasons described above" makes the reader scroll back. Restate the reason in place.

When a paragraph like the first one shows up in your own draft, it often helps to rework a dense design doc paragraph into a couple of plainer versions, then split the result into one fact per sentence.

Splitting a dense retry queue paragraph into two sentences with Rephrase AI on Clearer.

Habits that keep the doc readable

• Put a three line summary at the very top. Many readers stop there.
• Use diagrams for data flow and words for decisions.
• Keep each section brief enough that someone gets through it before their coffee cools.
• Write the decision even if it's "not yet." An undecided doc with a clear blocker is still useful.
• Move long appendices like benchmark output to linked pages.

After the review

Update the status to Decided and note who signed off. If the build drifts from the doc, add a short "what changed" note instead of rewriting history. The point of the doc is the record of why.

If a section still reads like one long breath after you've trimmed it, drop it into Rephrase AI with the Academic profile for a more structured alternative, and keep only the sentences where your system names and numbers come through intact.