Every design doc I’ve written or reviewed lives at the intersection of two conversations: the technical one the doc claims to be about, and the political one the organisation is actually having about scope, ownership, and budget. Pretending only the first exists is how designs get approved and still somehow ship in circles. This post is how I learned to write for both audiences without losing either.

Two audiences, two conversations

Every good design doc is answering two questions at once:

  • The technical question: how should this thing work?
  • The political question: who owns it, who funds it, who gets credit, who loses optionality, who has to say yes for it to happen?

The doc claims to be about the first. The meeting is usually about the second. If you only write for the technical audience, you’ll get comments like “this looks good, let’s scope it down” and then watch your scope get re-expanded in a slack thread three weeks later, without you.

How I learned this the hard way

At one of my earliest engineering-management stints, I wrote what I thought was a phenomenal design doc for an infrastructure consolidation. Architecture diagrams: clean. Tradeoffs: enumerated. Migration plan: atomic. Alternatives: considered.

The doc got approved in review. Six months later, the project had shipped about 40% of the plan, two adjacent teams were doing their own versions of the same work, and I was in a room trying to explain to a VP why we weren’t done. I walked out of that room and realised:

  • My doc never named the three VPs who had overlapping claims on the systems I was consolidating.
  • It never acknowledged that Team A’s on-call rotation was a constraint on the migration window.
  • It never said what we would deliberately not be doing, which meant other teams assumed their pet feature was in scope.
  • It never named who would own the consolidated system once built, which meant the answer became “nobody” by the time it mattered.

The architecture was fine. The doc failed on politics, and I learned — the hard way — that the politics are part of the design.

The template I use now

Every design doc I’ve written since has these sections, in this order. The political ones are load-bearing, not optional:

1. The problem (one paragraph, user- or operations-visible)
2. The constraints (teams, budgets, timelines, existing systems)
3. The proposal (one paragraph summary before the details)
4. Non-goals (what this explicitly does NOT do)
5. Alternatives considered (at least two; each with a reason it lost)
6. The technical design (diagrams + prose)
7. The migration / rollout plan
8. Ownership (names of humans; "the platform team" is not a name)
9. Open questions (what we don't know yet)
10. Decision log (what was decided in review, when, by whom)

The sections everyone expects are 3, 6, and 7. Those are where the architecture lives. But sections 2, 4, and 8 are where the doc either ships the project or quietly kills it.

Constraints are not footnotes

Section 2 should be the longest-debated section in review. Not the technical design. The constraints.

A constraint looks like:

  • “Team A’s on-call rotation cannot absorb more alerts — any new service must meet a zero-additional-pages bar before we flip traffic.”
  • “The database migration window is 2 hours per quarter. Any design that requires more is not shippable.”
  • “The budget for this project is $0 additional infrastructure spend — we must fit within existing capacity.”
  • “VP X has committed this feature to the board for Q3. A design that slips past Q3 is politically expensive regardless of engineering merit.”

If you write those down, you write the political conversation into the doc. The people reading it now know what they’re agreeing to or disagreeing with. The alternative — leaving those constraints implicit and hoping everyone shares your understanding of them — is how six people leave a design review with six different projects.

Non-goals are how you protect scope

Section 4 — non-goals — is the single highest-leverage section of any design doc.

It says, explicitly: “This proposal does not include X, Y, or Z. If you want those, that’s a different doc.”

In a healthy design review, the non-goals section is where scope creep gets caught early. Without it, scope creep happens silently in the months after approval, when stakeholders who weren’t in the review start assuming their adjacent concern is covered.

I now refuse to approve a design doc that has no non-goals section. A doc without non-goals is a doc that’s agreed to everything by omission.

Ownership in names, not titles

Section 8 — ownership — is the section where you either assign responsibility or leak it into the void.

Good:

Ownership: Amal H. owns the rollout. After rollout, the Inventory team (DRI: Ben L.) owns operations. SLOs are defined in ops/inventory.md. After 90 days of stable operation, ownership transfers to the Platform team (DRI: Priya N.) for long-term maintenance.

Bad:

Ownership: The Platform team will own this.

The bad version looks like ownership but it’s not — “the Platform team” has no calendar, no pager, no performance review. Naming a human creates a relationship between a person and a responsibility. Naming a team creates diffusion of responsibility.

Writing for review vs writing for approval

A subtlety most design docs get wrong: the doc you write for a healthy review is not the same doc you write for approval theater.

A review-friendly doc:

  • Has lots of non-goals.
  • Enumerates alternatives honestly, including the one the author thinks is worst.
  • Has an “Open questions” section full of genuinely unresolved things.
  • Ends with a decision log that gets filled in after review.

An approval-theater doc:

  • Has “The Plan,” presented as inevitable.
  • Dismisses alternatives in one sentence each.
  • Has no open questions because the author doesn’t want to look under-prepared.
  • Pre-fills the decision log with “approved.”

If your org’s design-doc culture rewards approval-theater docs, that’s the culture failing — but it’s also fixable, starting with your own docs. Write review-friendly docs and accept that some of them will be rejected. That’s how design review was always supposed to work. An approval rate of 100% is an approval process of 0%.

The 2026 twist

AI-assisted writing changes something here. I can now generate a “complete-looking” first draft of a design doc in 20 minutes. This is great for the technical sections — they come out structured, with tradeoffs enumerated, in a prose style that’s consistent.

It’s actively bad for the political sections. The LLM doesn’t know who the three VPs with overlapping claims are. It doesn’t know which team’s on-call is fragile. It doesn’t know what the budget pretense is this quarter vs the real budget.

My current workflow: let the AI draft sections 3, 6, 7, and 9. Write sections 1, 2, 4, 8, and 10 myself. The AI can help with prose on those too, but the substance has to come from me because it lives in people’s heads, not in the repo.

The one question I now ask every design doc

Before I approve or reject a design doc, I ask the author one question out loud: “Who will be unhappy if this ships exactly as written?”

If they can’t name specific people, the doc isn’t ready for review. Because those specific people exist — they always exist — and if the author doesn’t know who they are, those people will show up in month three asking why they weren’t consulted.

If the author can name them, the next step is “have you talked to them yet?” If the answer is no, go talk to them. If the answer is yes, the doc is probably ready.

That question has saved me more months of rework than any other habit I have.