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
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.