/better-documents

name: better-documents
description: >
  Apply communication best practices when generating or reviewing any document,
  presentation, report, memo, slide deck, proposal, or email. Use this skill when
  asked to write, create, draft, or generate a document or presentation — apply
  the principles at generation time, not as an afterthought. Also use when asked
  to "review my doc," "look at this deck," "does this make sense," "is this clear,"
  "improve this proposal," "check this before I send it," "make this more effective,"
  or any request to evaluate whether a document will land with its audience. Use
  this skill even when the request seems minor — a "quick look" or a "short memo"
  is exactly when these principles matter most.
metadata:
  version: 1.1.0

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](https://www.anildash.com/2024/03/10/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

| Mode | When to use | What you do | |---|---|---| | **generate** | "write me a proposal," "create a deck," "draft a memo" | Apply all five principles while producing the document; no separate report needed | | **full-review** | "review this doc," "look at this deck" | Run all five passes plus the reader test on an existing document, produce a structured report | | **rewrite** | "fix this," "make this better" | Apply all passes, reader-test the result, return a revised version | | **targeted** | "is the ask clear," "check the formatting" | Run only the relevant pass(es) | | **quick** | "quick look," "does this work" | Run passes 1 and 2 only, flag the top 3 issues |

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.

In review and rewrite modes, after completing each pass, briefly re-check that the changes made in that pass did not compromise earlier passes — for example, a reordering in Pass 2 must not reintroduce Pass 3 formatting problems. Fix any regression before moving on.

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?

If the audience is a board of directors, read `references/boardroom.md` before reviewing or generating. It covers how board members actually read, how power works in the room, and what the realistic goal of a board document is.

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