top of page

Write a Design Doc — Technical Writing for Engineers, Part 1

Shift Quality Editorial
11 minutes ago
7 min read
Technical Writing for Engineers · Part 1

A platform team spends three weeks building a new event pipeline. The design doc was approved in a single meeting: twelve pages, a clean architecture diagram, two thumbs-up emojis and one comment about a typo. In week four, the data team sees the pipeline for the first time and points out that it drops the ordering guarantee their reconciliation jobs depend on. Nobody on the platform team knew those jobs existed. The doc never mentioned ordering, and nobody who would have noticed was asked to read it.


The doc wasn't badly written. It described the plan clearly. What it didn't do was put the plan in front of the people most likely to object to it, in a form that invited objection.


The working claim for this part: a design doc has two jobs. It explains the plan, and it surfaces disagreement while changing course is still cheap. Most docs do the first and skip the second. Everything below is aimed at the second job, because that is where the time saved actually comes from.


Before you start


  • Pick a piece of work you're about to start that touches more than one team, or that you can't fully describe in a paragraph.

  • Find your team's design doc template, if there is one. You'll adapt it, not replace it.

  • List the teams whose systems, data or on-call rota your change could affect. You'll need this list in Steps 5 and 6.


Step 1: Decide whether this needs a doc at all (5 min)


Writing a doc for work that doesn't need one teaches people to skim docs. Malte Ubl's account of how design docs are used at Google gives a useful test. A doc earns its keep when the solution is ambiguous, because of the problem or the solution's complexity, when you need consensus across the organisation, or when cross-cutting concerns such as security, privacy and observability need attention. It's the wrong tool when it would just be an implementation manual, with no trade-offs or rationale to discuss, or when the solution is so obvious that there are no real alternatives.


Ubl also distinguishes sizes: larger projects might run to 10–20 pages, while incremental changes suit a "mini design doc" of one to three pages. Most enterprise work sits at the short end.


Test you can run: write two genuinely different ways to solve the problem, two sentences each. If you can't produce a second option that a reasonable engineer might pick, you probably don't need a doc. If you can't produce a first option, you need to understand the problem better before you write anything.


Step 2: Write the context and scope before the proposal (15 min)


Ubl's suggested structure opens with context and scope, then goals and non-goals, then the actual design, alternatives considered and cross-cutting concerns. The order matters. If the proposal comes first, reviewers evaluate your answer. If the context comes first, they evaluate whether you've understood the problem, which is the cheaper thing to get wrong and the more expensive thing to discover late.


Write the context in the reader's terms, not yours. "Checkout p99 latency has risen from 400ms to 1.8s since the catalogue migration, and support tickets about abandoned baskets have doubled" is context. "We need a caching layer" is a proposal wearing context's clothes.


Test you can run: ask someone from another team to read only the context section and tell you, in their own words, what problem you're solving and for whom. If their version doesn't match yours, rewrite the context before you write another word of design.


Step 3: Make goals checkable and non-goals uncomfortable (10 min)


A goal is useful if, at the end of the project, someone can answer yes or no to it. "Improve checkout performance" fails that test. "p99 checkout latency under 500ms at twice current peak traffic" passes.


Non-goals do a different job. A good non-goal is something a reasonable reader might assume you're doing, written down so they know you aren't. "We won't redesign the basket UI" is a fine non-goal if some stakeholders were hoping you would. "We won't rewrite the company in Rust" isn't, because nobody expected it.


Test you can run: for each goal, write the measurement you'd use to answer yes or no. For each non-goal, name one person who might have expected it to be in scope. A non-goal with no name next to it can be deleted.


Step 4: Write alternatives that were really in contention (15 min)


Ubl describes the alternatives section as listing designs "that would have reasonably achieved similar outcomes", with the focus on "the trade-offs that each respective design makes and how those trade-offs led to the decision". The word that matters is reasonably. A list of strawmen, each dismissed in a line, tells reviewers the decision was made before the doc was written.


For each real alternative, give what it would cost, what it would give you, and the specific reason you didn't choose it. Then say what would have to be true for you to change your mind. That last line is the most useful thing in the section, because it tells a reviewer exactly what evidence would move the decision.


Test you can run: show your alternatives section, without your recommendation, to a colleague and ask which they'd pick. If they all pick your option instantly, the alternatives are probably strawmen. If they pick a different one, you've found a conversation you needed to have.


Step 5: Name the cross-cutting concerns, including data (10 min)


Cross-cutting concerns are where the expensive surprises live, because they belong to teams who aren't in the room. Go through security, privacy, observability, operability and, explicitly, data: what data the change reads, writes, reorders, delays or drops, and who downstream depends on its current behaviour.


The event pipeline in the opening failed here. Ordering wasn't a platform concern, so nobody on the platform team thought of it as a requirement. It was a downstream assumption that had never been written down.


Test you can run: for each concern, write one sentence or "n/a because …". Then, for the data line, name every downstream consumer and the one property of the current behaviour each of them would notice changing. If you can't name the consumers, that's your first open question.


Step 6: Run the review to find objections, not approval (15 min)


Choose reviewers by who is most likely to disagree, not by who is quickest to approve. That usually means at least one person from each affected team on your Step 5 list, plus someone senior enough to say "we tried this in 2023".


Ask each reviewer a specific question rather than "any thoughts?" For example: "Does the ordering change in section 4 break anything you run?" Give a fixed window for asynchronous comments, then hold a short meeting only for the threads that didn't resolve in writing. Record each decision in the doc, next to the thread that produced it.


Test you can run: after the review, count the comments that changed the design versus the ones about wording. If none changed the design, either the design was unusually right or the right people didn't read it. Check which by asking one affected team directly.


Step 7: Keep the doc honest after approval (5 min)


An approved design doc starts going out of date the day implementation begins. Don't try to keep the whole doc current. Instead, when a significant decision changes, record the change as an architecture decision record (Part 2) and link it from the top of the design doc, with a one-line note on what changed.


Test you can run: open a design doc from a project that shipped six months ago. Could a new engineer tell, from the doc and what it links to, which parts still describe the system? If not, add a status line and links before the next person relies on it.


Worked example (composite)


A composite scenario, not a real company or project.


A payments platform team at a mid-sized insurer needed to move card tokenisation from an ageing on-premises service to a managed cloud vault. The first draft of the design doc was eight pages: a thorough description of the new vault integration, with one paragraph of alternatives.


The tech lead ran the Step 1 test and could name two real alternatives: wrap the old service behind a new interface and migrate later, or move straight to the vault. That justified the doc. The Step 2 test was more revealing. A reviewer from finance operations read only the context and summarised it as "a security upgrade". The team had meant "a cost and resilience change". They rewrote the context around the actual problem: the on-premises service had had two outages in a year, and its hardware support was ending.


Step 5 produced the decisive finding. Listing data consumers, the team found that the monthly chargeback reconciliation matched transactions by the old token format. The new vault issued tokens in a different format. Nobody on the platform team had known that reconciliation existed, and it wasn't in the first draft.


The review in Step 6 included someone from finance operations for the first time. Their one comment moved the design: the team added a token-mapping table and a parallel-run month, and dropped a planned cutover date that would have landed in the middle of quarter-end close. The doc grew by a page and a half. The project slipped two weeks on paper and avoided a reconciliation failure during close.


Trade-offs to make deliberately


Choice

You gain

You risk

Write a full doc

Shared understanding; objections surface early

Weeks of writing for work that didn't need it

Write a mini doc (1–3 pages)

Speed; people actually read it

Cross-cutting concerns get skipped

Invite likely objectors

The expensive problems surface now

A slower, harder review

Approve in one meeting

Momentum

Silence mistaken for agreement

Keep the doc fully current

Accurate reference

Maintenance nobody does; use linked ADRs instead


Common failure modes


  • Solution-first context. The doc defends a decision instead of making one.

  • Strawman alternatives. Reviewers can see the decision was made before the writing started.

  • Missing data consumers. The surprise arrives from a team that was never asked.

  • Approval by silence. No comments is not the same as no objections.

  • The doc that never changes. Implementation diverges, and the next reader trusts the wrong version.


Final takeaway


A design doc that only explains the plan saves you very little. The value is in finding the objection while it costs a paragraph rather than a rewrite: context the reader can restate, goals you can check, alternatives someone might pick, data consumers named, and reviewers chosen because they might say no. Your next action: before your next design review, add one reviewer from the team most likely to object, and ask them one specific question about the section that affects them.


Sources




Continue the Technical Writing for Engineers path



bottom of page