What makes a design document worth reviewing, and what makes reviewers ignore one?

What is being tested

Whether you know that writing improves the thinking, and which sections make review productive.

What makes it worth reviewing

A summary that stands alone. Most readers will read only this. If it is complete, that is fine and you have served them.

Explicit non-goals. Stating what the design deliberately does not address prevents both scope creep and the later accusation that something was overlooked. It is one of the two sections that does most of the work.

Alternatives considered, with the reasoning for rejection. The other. A reviewer's most useful contribution is usually "you dismissed option B too quickly", and that is only possible if option B is on the page. A document presenting one option invites approval, not review.

Consequences, including what gets worse. A design with no stated downside has not been understood, and any experienced reviewer will distrust it.

Open questions, stated honestly. A document with none is either trivial or dishonest. Naming the uncertainty is what invites the help you actually need.

Written before the decision, so review can change something. Circulated afterwards it is theatre and reviewers learn not to bother.

What makes reviewers ignore one

• Length. Twenty pages where two would do. Length is a cost imposed on every reader.
• Conclusion buried on page fourteen.
• Straw-man alternatives — one real option and two obviously bad ones. Transparent, and it undermines the whole document.
• Adjectives instead of numbers. "Fast" and "scalable" cannot be reviewed. "p99 under 300 ms at 2,000 requests per second" can.
• No open questions, signalling either triviality or concealment.
• No deadline for comments, so review never happens.

Why writing improves the thinking

Vague reasoning survives a conversation and does not survive a paragraph. A listener nods past a gap; the page makes it visible to the author.

This is why the written design document works so well as a practice: the review happens where changing your mind costs nothing, and the act of writing has already removed the weakest arguments before anyone else reads it.

The editing discipline

The second draft should be shorter. Front-load the conclusion, use concrete nouns, and cut anything that does not change a reader's understanding.