The manual is the humblest and hardest genre. No one praises a good set of instructions, but a bad one can strand a whole team on the same step. It doesn't chase style — only one thing: let someone who isn't inside your head follow along and get it right. The README, the API doc, the runbook, the onboarding guide — all of it is this genre. Today, four people who truly studied "how to teach someone to do something" help us write it so well that nobody has to ask.
Principle 01
Chunk the Steps: One Action Each, Condition Before Action
Chunk the Steps — Condition Before Action
Redish · Numbering · Imperative
The Principle + In Their Words
The smallest unit of instruction is one executable action. Break flowing prose into numbered steps, one action per step, in the imperative (verb first). The key: put the condition, location, or purpose before the action — don't let the reader act first and only then discover there was a prerequisite.
"Put the condition or the location before the action. People act as soon as they read the action; if the condition comes afterward, they've already done it wrong."
— Ginny Redish, Letting Go of the Words (2007)
Why It Works
People don't read instructions to admire them; they read to do. Their attention is a laser fixed on "which button next." Hence two iron rules: one, actions must be short enough to be caught while scanning — a numbered list with a leading verb beats one long "first… then… next…" paragraph; two, because a reader's hand moves the instant they hit the verb, any prerequisite (back up first, admins only, never in production) must come before the action, or it arrives too late.
The Rewrite
Click Delete to remove the record. Note that you should export a backup first, or the data cannot be recovered.1. Export a backup — deleted data cannot be recovered.
2. Click Delete.The fatal prerequisite ("back up first") moves ahead of the action and becomes its own step — by the time the reader reaches step 2, the backup is done.
✗ Cramming several actions into one step ("configure and restart and verify") — one action per step
✗ Prerequisites after the action ("click Submit — remember to fill required fields first"); they already clicked
✗ Prose instead of numbering, so the reader can't scan to find which step they're on
✗ Skipping a step: the author assumes "obviously you log in first," and the reader stalls at step one
This Week's Exercise + A Question
Take a setup or install passage you've written and convert it into numbered steps: each an imperative, verb first, every prerequisite and warning moved ahead of its action. Count how many "do this — actually, do it even earlier" traps you had. Question: The last time someone's doc stalled you, was it "not written down," or "wrong order"?
Principle 02
The User's Mental Model: You Write for Their Model, Not Yours
The User's Mental Model
Norman · Conceptual Model
The Principle + In Their Words
You (the author) carry a full model of how the system works; the reader doesn't. What they can see — the interface, the naming, the docs — is their only source (Norman calls it the "system image"). A good instruction's job is to install, through that image, a model that is good enough to predict the next step.
"A good conceptual model allows us to predict the effects of our actions. Without a good model, we operate by rote, blindly; we do operations as we were told to do them."
— Don Norman, The Design of Everyday Things (1988/2013)
Why It Works
This explains "I followed the steps and still can't do it": pure steps give rote, not a model. The moment the reader hits a case the doc didn't cover, they're lost — they don't grasp the "why." So the best instructions add a "because" at key points: not explaining every detail, but giving one mental anchor from which the reader can infer the un-written cases. It's also the cure for the "curse of knowledge" — you know the system too well to remember the reader is a blank slate.
Designer's Modelyour full picture of how it works
↓
System Imageinterface · naming · docs — the only channel
↓
User's Modelwhat the reader infers, and predicts from
The designer's model never passes to the user directly; the user can only infer it from the "system image." How well you write decides how cleanly that inference goes
The Rewrite
Run flush to clear the cache.Run flush to clear the cache. The cache is just a temporary in-memory copy — flush drops the copy, never the source data — so it's safe to run.One line of "why it's safe" gives the reader a model: next time they face "should I flush?" they can decide for themselves instead of asking you.
When to Use It + Common Mistakes
✓ API behavior notes, error meanings, "what this toggle affects," architecture onboarding, CLI help
✗ Actions only, no model — the reader stalls the moment they leave the template
✗ The reverse: dumping every implementation detail to show off, drowning the "good-enough" model
✗ Naming that contradicts behavior (a "Save" button that submits) — the system image itself lies
✗ Assuming the reader shares your concepts; jargon and internal acronyms left unexplained
This Week's Exercise + A Question
Find one pure how-to line in your docs and add a "why / what it's really doing," enough that the reader can infer one adjacent case you didn't write. Question: Do "give a model" and "stay concise" conflict? Which "because" earns its place, and which is you showing off?
Principle 03
Error Prevention: The Best Error Message Is One That Can't Fire
Error Prevention Over Error Messages
Nielsen · Poka-yoke
The Principle + In Their Words
A master of instruction isn't satisfied with "spell out how to do it right." They also ask "where is the reader most likely to go wrong," then set a guardrail just before that step — a warning, a constraint, a safe default, a verification. Better than a good error message is making the error unable to happen.
"Good error messages are important, but the best designs carefully prevent problems from occurring in the first place."
— Jakob Nielsen, 10 Usability Heuristics, #5 (1994)
Why It Works
An error message is after-the-fact repair; prevention is up-front interception — an order of magnitude cheaper. For a doc writer, "error prevention" has concrete moves: one, flag the dangerous action (irreversible / touches production) and set the warning off visually from the body; two, give a safe default ("leave it unless you have a reason"), sparing the reader a decision they're not equipped to make; three, turn implicit prerequisites into explicit checks. Norman calls this class of design a forcing function (poka-yoke) — in a doc, it's making the mistake hard to make.
The Rewrite
Change the port in config.yaml, then restart the service.⚠ Test environment only. Production port changes require approval.
1. Set port in config.yaml (default 8080 — leave it unless you have a reason).
2. Restart, then verify with curl localhost:<new-port>.Three guardrails: a danger boundary (test only), a safe default (leave it), a verification step (confirm it took) — the mistake is now hard to make.
When to Use It + Common Mistakes
✓ Runbooks, production SOPs, irreversible commands, migration/rollback guides, error-prone configs
✗ Warning placed after the action, or buried inconspicuously in the body
✗ A hollow "please be careful" with no information — state the concrete consequence
✗ No default, forcing a choice the reader has no background to make
✗ No verification step, so the reader finishes not knowing if it worked
This Week's Exercise + A Question
Take a doc with a "dangerous action" and, for each irreversible step, add three things: a warning naming the concrete consequence (ahead of the action), a safe default, and a "how to confirm success" check. Question: Where's the line between prevention in the doc and prevention in the product itself (disabled buttons, confirmations)? What should the doc never have to cover?
Principle 04
Minimalist Instruction: Cut Until the Reader Can Move
Minimalist Instruction
Carroll · Krug · Cut
The Principle + In Their Words
People don't read manuals; they want to get going. Minimalism (Carroll) isn't writing less — it's cutting everything that stands between the reader and their first action: long preambles, obvious explanations, exhaustive options — leaving only the minimum that lets them act now and recover from errors on their own.
"The idea of minimalism is to reduce the extent to which instructional materials obstruct learning, and to find ways to support the learning activities already going on."
— John M. Carroll, The Nurnberg Funnel (1990)
"Get rid of half the words on each page, then get rid of half of what's left."
— Steve Krug, Don't Make Me Think (2000)
Why It Works
Why does "less" work better? Because a reader's patience is scarce; every filler sentence spends it, making them likelier to give up and just poke around. Carroll's counterintuitive finding: give beginners a thicker manual and they learn slower — the bulk delays doing. Minimalism has three moves: cut the happy-talk intro ("Welcome! This tool is designed to…") and lead with the first action; cut what the reader already knows (don't explain what "click" means); trade "complete" for "enough" — cover the 80% main path, link edge cases out.
The Rewrite
Welcome! Before we begin, we recommend familiarizing yourself with the overall process. This tool is designed to help you deploy more efficiently. First, make sure all dependencies are installed, and then we can get started.Deploy in 3 steps:
1. make deps
2. make deploy
3. Open /health — "OK" means success.Forty words of warm-up and "designed to help" gone; three actions straight up. The reader is on step one within ten seconds.
✗ Happy-talk intros; zero-information transitions like "as we all know" / "it's worth noting"
✗ Exhaustiveness: stuffing every edge option into the main flow, drowning the main path
✗ Explaining what the reader already knows (don't teach what a browser is)
✗ Mistaking "minimal" for "missing" — error-recovery info can't be cut; that's what beginners need most
This Week's Exercise + A Question
Take a quickstart and apply Krug's rule in two passes (cut half, then half of what's left), until the reader can start step one before finishing the read. Check: did you actually lose information? Question: When do "minimal" and "complete" have to conflict? Is the boundary the same for a surgical checklist and an app's onboarding?
Going Deeper
Good instruction erases the author's presence; the essay and the speech chase a distinct voice — the opposite. How does one person switch between the two modes?
The highest praise for instruction is "transparent" — the reader breezes through the task without noticing the prose. That's the reverse of the "voice" prized in essays and speeches, yet the underlying craft is shared: both demand extreme consideration for the reader. The difference is who you serve — instruction serves task completion, the essay serves resonance of thought. The mark of a mature writer is judging, moment to moment, whether to vanish or to appear — and switching cleanly. Voice isn't for everywhere; it's for when it belongs.
What traps are unique to writing instructions in Chinese?
Chinese breeds long "的"-strings and subject-less sentences, yet instruction most needs short clauses and an explicit subject (who does what). The imperative naturally drops the subject in Chinese, which is an advantage ("点击保存" is clean); the danger is that "请您"-style politeness dilutes the action, and word order makes "condition before action" harder to arrange. Chinese instructions also love soft words like "即可," "相关," "进行" — enemies of clarity. The cure is the same as in English: lead with the verb, one action per step, cut the filler.
When do pictures (screenshots, flowcharts, wordless IKEA diagrams) beat text steps?
When the key information is spatial (where the button is, how the wires connect), a picture far beats text — IKEA manuals are nearly wordless for exactly this reason. When the key is sequence and conditional logic (judge A first, then decide B), text plus numbering is clearer. The strongest form has each do its own job: the screenshot shows "where," the text says "what and why." The trap is a screenshot captioned "click here as shown" — don't repeat in words what the image already says.
AI can generate docs from code and answer questions conversationally. Will "writing a static manual" be replaced?
The form will change; the craft grows more valuable. AI can produce API references and instantly answer "what does this parameter mean" — the mechanical layer, derivable from code, it does well. But it can't infer "where the user will make a fatal mistake," "which prerequisite must come first," "what to cut and what to keep" — these come from empathy for a real reader and judgment about the task. Future "doc writing" is less typing, more designing information architecture, flagging danger, defining the mental model. The person who thinks for the reader is scarcer than ever.
Do "make users awesome" (Kathy Sierra) and "don't make me think" (Krug) contradict each other?
No — they're layered. Krug's "don't make me think" targets the interface and the path: finding a button, walking a flow, chores that shouldn't cost brainpower. Sierra's Badass targets capability: the tool should make users powerful at the real task. Good instruction does both — drive operational friction to zero (no thinking about how to click) and steer the cognitive investment somewhere worthwhile (understanding the model, mastering the skill). The brainpower you save gets spent where it counts.