# How do I write a technical design doc the team will actually read?

> Frame the doc as a discussion organised toward a decision: problem and non-goals up top, rejected alternatives visible, and an explicit approval asked for.

- Asked: 2026-11-11
- Answered: 2026-11-17
- Tags: Career
- Source: https://muhammetsafak.com/just-ask/write-technical-design-doc-team-will-actually-read/
- Language: en-US
- Author: Muhammet Şafak

---
**Question:** Before starting a new feature or an architectural change, I write an RFC/design doc. But my docs usually get a couple of thumbs-up emojis and then everyone builds something different anyway.

So the doc either isn't read, or if it is, it doesn't turn into a shared decision. How do I write a technical design doc the team will actually read and align on? I'm looking for behavioural, lived-experience advice more than formatting tips.


## Short answer

The reason everyone builds something different isn't the doc's length; it's ambiguity and the absence of an explicit decision.

## Context

A thumbs-up is not an approval. The doc that works is the one that [forces the reader to align](https://muhammetsafak.com/just-ask/how-does-the-nature-of-the-work-change-on-the-jump/).

## What to do

1. **Lead with the problem and context, not the solution.** People skim. The first paragraph should say "what we're solving, why now, under which constraints". Put a 3–4 sentence TL;DR at the very top so everyone grasps the point before diving into solution detail.

2. **State your non-goals loudly.** This is the number-one reason people build different things: scope stays vague, and everyone fills the gap with their own assumption. A "this doc does not cover X" list prevents more conflict than the solution itself.

3. **Write down the alternatives you rejected, and why.** This is where alignment actually happens. If you don't say "I chose B over A because...", the reader leaves with the A in their head and builds that. The rejected options are the most valuable part of the doc.

4. **Keep it short — length is a cost.** A doc nobody finishes aligns nobody. Cut ruthlessly. A ten-page design is usually a two-page decision plus an argument you could have avoided.

5. **Force an explicit decision; silence is not consent.** Tag specific people on specific sections, ask concrete questions ("do you approve this schema?"), set a review deadline. Close it with a 30-minute decision meeting if you must. Aim for an explicit "approved / here's my objection", not an emoji.

6. **The doc is a living record, not a monument.** Fold the discussion back into it, note decisions inline, keep a changelog. After approval it must remain the source of truth: link to it from tickets, and update it when reality diverges — otherwise it's dead within two weeks.

**Bottom line:** personally I'd frame the doc not as "a document to be read" but as "a discussion organised to reach a decision". I write for the skimmer: problem and non-goals up top, rejected alternatives visible, the decision explicitly asked for. Most importantly, I never mistake thumbs-up for alignment — everyone building something different is proof that nobody actually committed to anything. Without a forcing function (a deadline, an assigned approver, a short decision meeting) that loop won't break.

*Compiled from questions I have run into in the field or been asked.*

## Related Reading

- [Visibility: why writing is a career investment](https://muhammetsafak.com/blog/visibility-writing-as-a-career-investment/) — Blog
- [How do I take blunt code review feedback without getting defensive?](https://muhammetsafak.com/just-ask/take-blunt-code-review-feedback-without-getting-defensive/) — Just Ask
- [How do I mentor a junior without just doing the work for them?](https://muhammetsafak.com/just-ask/mentor-junior-without-doing-their-work/) — Just Ask
- [How does the nature of the work change on the jump from senior to staff?](https://muhammetsafak.com/just-ask/how-does-the-nature-of-the-work-change-on-the-jump/) — Just Ask
