How to Write Engineering Design Docs That Get Read and Approved

What and Why

Design docs are the operating system of engineering organizations. They turn ambiguous ideas into reviewed decisions, surface disagreement before code is written, and create an audit trail for why a system looks the way it does. A good design doc saves weeks of rework. A bad one wastes a team’s time and is the reason senior engineers ignore your next one.

The interesting observation: the writing skill is not optional for senior engineers. Promotion committees, architecture reviews, and cross-team alignment all run on docs. If you cannot write one that gets approved, you cannot operate at scale.

Mental Model

A design doc is a sales document for a technical decision. The audience is busy, skeptical, and probably skimming. Your job is to make the right answer obvious in five minutes of reading and to provide depth for the reviewer who wants to challenge a specific section.

Three readers to imagine:

• The skimmer. Reads the title, summary, and headings. Wants to know what this is, why, and whether they need to engage.
• The reviewer. Reads the problem, alternatives, and proposed solution. Wants to check that you considered their concerns.
• The implementer. Reads everything. Will build from the doc weeks from now and needs the details.

If you write for only one of these, the other two will not approve.

Architecture

+---------------------+
| Title + Status      |
| Authors, Reviewers  |
+---------------------+
| TL;DR (3-5 lines)   |
+---------------------+
| Context / Problem   |
| Goals & Non-Goals   |
+---------------------+
| Proposed Design     |
|   - Overview        |
|   - Detail sections |
|   - Data model      |
|   - API             |
+---------------------+
| Alternatives        |
| Trade-offs          |
+---------------------+
| Rollout / Risks     |
| Open Questions      |
+---------------------+

The sections, with what each is for:

• Title and status. Draft, in review, approved, implemented, deprecated. Status communicates whether you need feedback or just acknowledgment.
• TL;DR. Three to five lines. What we are building, why, and the headline trade-off. If the reader stops here, they should know whether to engage.
• Context. What is the situation. Why does it need a decision now. Links to prior docs and incidents. Skip generic background; assume an engaged reader.
• Goals and non-goals. Explicit. Non-goals are how you defend scope creep in review. “Not solving multi-region; that is a follow-up.”
• Proposed design. The meat. Start with a high-level picture. Then the data model, the API, and the key flows. Use diagrams. Resist the urge to dump implementation details that belong in code.
• Alternatives considered. Two or three. For each: short description, why it was rejected. Without alternatives, your proposal looks unconsidered.
• Trade-offs. The honest section. What does this design make harder. What guarantees does it not provide. What costs more than the alternative.
• Rollout and risks. How does this ship. Feature flags, migration, rollback. What could go wrong, and how would you notice.
• Open questions. Issues you want the reviewer to weigh in on. Numbered so reviewers can answer specifically.

Trade-offs

Length. Longer is not better. Three pages with the right content beats fifteen pages of padding. Senior engineers who write tight docs ship faster decisions.

Detail level. Below the API surface, details belong in code. Above the proposed design, philosophical context belongs in a separate vision doc. Stay in the middle layer.

Diagrams. One good diagram beats five paragraphs. ASCII or hand-drawn is fine; you are not making a poster. The point is to convey structure quickly.

Tone. Confident but not defensive. You are presenting a recommendation, not selling a product. Acknowledging weaknesses builds credibility; pretending none exist destroys it.

Anonymized lessons. If a prior approach failed, reference it without blame. “An earlier version of this service used X; we observed Y, so we are moving to Z.” That is engineering memory at work.

The biggest trade-off is reviewer attention. You get one good read from each reviewer. Spend it well. Don’t bury the trade-off section behind ten pages of implementation detail. Don’t open with a wall of context. Get to the headline fast, then let the reader dive in.

Practical Tips

1. Write the TL;DR last. You will not know the headline until you have written the body.
2. Make the decision testable. State the proposed answer to each open question, even if tentative. “Proposed: use Postgres. Open question: row-level versus partition-level locking” beats “should we use Postgres?”
3. Date and version it. Decisions change. The doc is a snapshot of intent at a moment. Future readers should know which version of reality applies.
4. Time-box reviews. “Please comment by Friday.” Without a deadline, comments arrive forever and the doc never gets approved.
5. Address comments inline and link the resolution. Don’t ignore them, don’t silently rewrite the doc to match the loudest critic. Show the reader how the doc changed in response.
6. Walk the doc in person once. A 15-minute review meeting with the senior reviewers catches the hardest objections faster than async comments.
7. Track non-goals fiercely. Reviewers will ask “but what about X?” If X is a non-goal, point them at the non-goal section. If X is genuinely missed, update the doc.
8. Re-read after a day. The first draft sounds clearer to you than to anyone else. A 24-hour gap exposes the assumptions you forgot to make explicit.

A short opening template:

# [System Name] Design

Status: Draft / In Review / Approved
Authors: ...
Reviewers: ...
Last updated: 2026-06-28

## TL;DR
We will build X to solve Y. Key trade-off: we accept Z to gain W.

## Goals
- ...
## Non-Goals
- ...

That opening gets a skimmer to a decision in twenty seconds.

Wrap-up

Design docs are the medium through which engineering organizations think out loud. Writing one that gets approved is a skill: structure, clarity, honest trade-offs, and respect for the reader’s time. Senior engineers write tight, opinionated docs that surface the decisions reviewers actually need to make. Junior engineers write long, neutral docs that summarize the world. The difference is judgment about what to leave out. Practice that, and your docs become the artifact that other people imitate.