practice

Written Communication

Writing that reaches more people than any meeting, survives longer, and forces the thinking that verbal explanation lets you skip.

writingdocumentsasyncclarityreview

Definition

Written communication is the architect's highest-leverage medium: it scales beyond the room, persists, and can be reviewed asynchronously by people in other time zones.

Why writing improves the thinking

Vague reasoning survives a conversation and does not survive a paragraph. Writing forces completeness — a gap that a listener would nod past becomes visible on the page to the author.

This is why the written design document as the primary architectural artefact works so well as a practice: the review happens on the document, where changing your mind costs nothing, and the act of writing has already removed the weakest arguments.

The structure that works for a design document

A summary that stands alone. Most readers will read only this, and that is fine if it is complete.
The problem and why it matters now.
Goals and — importantly — non-goals. Stating what the design deliberately does not address prevents both scope creep and the later accusation that something was overlooked.
Options considered, with the reasoning for rejection. The reviewer's most useful contribution is usually "you dismissed option B too quickly", which is only possible if option B is on the page.
The recommendation and its consequences, including what gets worse.
Open questions, stated honestly. A document with no open questions is either trivial or dishonest.

Craft that matters

Front-load. Conclusion first; detail after. Readers stop early.
Short sentences and concrete nouns. Abstraction is where imprecision hides.
Numbers, not adjectives. "Fast" is unusable; "p99 under 300 ms at 2,000 requests per second" is a requirement.
Say what you are uncertain about. Stated uncertainty is credible; concealed uncertainty is discovered.
Edit down. The second draft should be shorter. Length is a cost imposed on every reader.

Failure scenarios

A twenty-page document where two would do, so nobody reads it.
Conclusion buried on page fourteen.
No non-goals, so scope expands through review comments.
Options presented with one obvious winner and two straw men, which is transparent.
Written after the decision, so review is theatre.

Interview question

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