Skip to content
Muhammet Şafak
tr
Answered:

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


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.

Answer

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.

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

Comments

Sign in with your GitHub account to join the discussion. Comments are stored in GitHub Discussions.

More Questions

All questions

Search the site

Start typing to search posts, projects and pages.

Esc to close Powered by Pagefind