msewell Writing Persuasive Documents
Write to change what readers think — not to show what you know.
Workflow: Writing a new document
- Identify specific readers. Determine what they already believe, what they want solved, what they would doubt, and what language signals value in their world.
- Identify the core instability. Find what is wrong, at risk, or misunderstood — instability is where value lives.
- Open with problem + stakes + response. State the problem within 3 sentences. Show the cost or benefit. State what the document will do about it. No background preamble.
- Use tension language. Lead with but, however, although, despite, yet, inconsistent, contrary to. Avoid stability language (also, furthermore, in addition, moreover) in the opening.
- Show cost of inaction or benefit of action. Quantify with money, time, risk, or competitive position. Match the framing (cost vs. benefit) to what resonates in the reader's community.
- Argue, don't explain. Anticipate what the reader will doubt and address each doubt directly. Do not narrate your research process.
- Address the strongest counterargument. Acknowledge it, then show why it doesn't hold. This builds trust.
- Challenge what's wrong, not what's missing. "The current approach produces the wrong result" is stronger than "nobody has studied X."
- Build evidence toward the claim. Connect sources to create tension and instability — do not catalogue them neutrally.
- Restructure for the reader. Put the most important claim first. Follow the reader's decision process, not your discovery chronology. Cut everything that doesn't serve the argument.
- Self-review. Check against the revision checklist in references/02-advanced-techniques.md.
Workflow: Reviewing an existing draft
- Read the full document.
- Check against the revision checklist in references/02-advanced-techniques.md.
- Identify the 3 highest-impact violations.
- For each issue, provide a concrete before/after rewrite demonstrating the fix.
- Name which principle each fix addresses (see quick reference below).
Quick reference
| Principle | Instead of... | Do this... |
|---|---|---|
| Value first | Showing what you know | Changing what they think |
| Specific readers | Writing for "the audience" | Writing for the 3 people who decide |
| Problem-first openings | Background, definitions, history | The instability + its cost, immediately |
| Tension language | Also, furthermore, in addition | But, however, although, despite |
| Cost of inaction | "There is a gap" | "This is costing us $X / exposing us to Y" |
| Argue, don't explain | "We analyzed X and found Y" | "The obvious objection is Z — here's why it doesn't hold" |
| Challenge, don't fill | "Nobody has studied X" | "The current approach to X is producing the wrong result" |
| Restructure for readers | Draft organized by your discovery process | Document organized by their decision process |
Principle selection
Not every document needs all principles equally. Adjust intensity to context:
- Proposals / recommendations / business cases: Apply all principles at full intensity.
- Executive summaries: Prioritize problem-first opening, cost of inaction, tension language.
- Status reports: Apply tension language and cost framing where genuine issues exist. Do not manufacture drama.
- Technical briefs: Prioritize argue-don't-explain and evidence building.
- Emails requesting action: Prioritize value first, problem opening, cost of inaction. Keep short.
Detailed principles and examples
For full explanations with before/after examples:
- Principles 1–5 (value, readers, openings, tension, stakes): references/01-core-principles.md
- Principles 6–10 + revision checklist (argument, challenge, structure, evidence, review): references/02-advanced-techniques.md