Better Documents

Document Review

Apply communication best practices when generating or reviewing any business document — whether the right message reaches the right audience in the right order.

This skill applies the principles from Anil Dash's Make better documents.

Scope

This skill covers business documents: presentations, slide decks, proposals, reports, memos, briefs, one-pagers, and emails. It does not cover UI, web components, or frontend applications — use the frontend-design skill for those.

The design principles here differ from frontend design in important ways:

• Restraint over expression. UI benefits from bold aesthetic commitment and distinctive visual personality. Business documents benefit from getting out of the way of the content. Most people reading a board deck or a client proposal are not there to appreciate the typography.
• The audience can't interact. A web interface rewards exploration. A document gets one read, often skimmed, often on a small screen or printed. Every design choice that draws attention to itself is attention stolen from the message.
• Non-designers are both authors and audiences. UI is built and consumed with design context nearby. Business documents are built by operators, analysts, executives, and founders — and read by the same. Complexity that a designer handles intuitively becomes noise for everyone else.

Modes

Default to generate when producing a new document from scratch. Default to full-review when given an existing document with no other instruction.

---

The Five Passes

Apply these in order. Each targets a different failure mode.

Pass 1 — Audience and Purpose

The most common reason documents fail: they were written for the author, not the reader.

Check for:

• Missing context: Does the document assume knowledge the audience may not have? Flag any jargon, backstory, or acronyms that aren't explained.
• Buried ask: Is there a request, decision, or action needed? If so, is it stated clearly in the first third of the document — not saved for the end?
• Author-centered opening: Does the document open with the author's anxieties, backstory, or credentials rather than shared context? Flag and suggest reordering to start from common ground.
• Missing deadline or stakes: If a decision or response is needed, is the timeline stated? Is the reason for that timeline explained from the audience's perspective, not just the author's?

Severity guide:

• CRITICAL — The core ask or decision is absent or appears only at the end
• MAJOR — The audience is unclear; the document would read differently to different readers
• MINOR — Context gaps that could be filled with a sentence

---

Pass 2 — Structure and Sequencing

Order signals importance. Audiences assume the first thing is the most important. If it isn't, they'll be confused or dismissive before they reach the part that matters.

Check for:

• Creation-order sequencing: Is the document structured in the order it was written (background → analysis → conclusion) rather than the order the audience needs (conclusion → supporting logic → call to action)?
• Murder mystery structure: Does the document build to a reveal rather than stating the point upfront? Flag any document where the key conclusion or request appears in the second half.
• Unannounced ordering: If the document is ordered chronologically, by category, or by any logic other than importance, is that explicitly stated? If not, the audience will hunt for meaning in the sequence.
• Key information in the wrong channel: Is anything critical only in speaker notes, appendices, or footnotes? Central points belong in the main body.

Severity guide:

• CRITICAL — The document's conclusion or core request is in the second half
• MAJOR — Ordering is non-obvious and unexplained
• MINOR — Supporting points could be reordered for better flow

---

Pass 3 — Formatting Restraint

Over-formatting is the most visible symptom of unclear thinking. When everything is emphasized, nothing is.

Check for:

• Emphasis overload: Are bold, italic, underline, and color being combined on the same text? Flag any instance of two or more emphasis types on a single element.
• Underlines on non-links: Flag every underline that isn't a hyperlink. Underlines exist to signal clickability; using them decoratively confuses readers.
• Color proliferation: Count distinct colors in use (excluding images). More than two is almost always a problem. More than three is always a problem.
• Border clutter: Flag tables and sections with heavy borders. White space separates content more clearly than lines.
• Filler visuals: Flag images, icons, or clip art that aren't specific to the content's message. A blank space is better than a stock photo.
• Formatting inconsistency: Do headings, titles, or labels vary in size, weight, or color across the document without clear reason? Flag inconsistencies that will read as meaningful to an audience even if they weren't intentional.

Severity guide:

• CRITICAL — Formatting inconsistencies that will be read as semantic signals (e.g., random font changes mid-document)
• MAJOR — Overuse of emphasis that makes it impossible to identify what's actually important
• MINOR — Minor decoration that adds noise without adding meaning

---

Pass 4 — Wayfinding and Density

Audiences need to know where they are in the story, and how far they have to go.

Check for:

• No orientation: Is there any indication of structure — a brief outline, section headers, or progress markers — for documents longer than one page or five slides? If not, flag.
• Unsummarized data: Does any chart, table, or data display appear without a title or caption that states what it shows? Readers shouldn't have to interpret data cold. Flag every chart or table whose title doesn't answer "what does this show?"
• Unanswerable questions: Are there open-ended questions in the document (as headers or prompts) that can't actually be answered with a choice? Flag any question that could lead to a philosophical discussion instead of a decision. Good: "Do we go with Option A or Option B?" Bad: "How do we improve?"
• Dense, unbroken prose: Are there paragraphs longer than ~6 lines where bullet points would make the content more skimmable without losing meaning?

Severity guide:

• CRITICAL — Data presented without any interpretive framing
• MAJOR — Long documents with no structural signposts
• MINOR — Questions that could be made more answerable

---