Chapter 22: Instructions and Procedures: Writing That Tells People How to Do Things

"If the user can't use it, it doesn't work." — Susan Dray

Chapter Overview

A person is standing at a copier with a paper jam, holding your instructions, and they are getting angrier by the second. Step 4 says "open the rear access panel." There is no rear access panel—or rather, there is, but it's labeled "Door C," and the instructions never mentioned that, and the reader has now spent four minutes turning the machine around looking for the word rear. This is the moment that defines procedural writing, and it has almost nothing in common with the writing in the rest of this book. The reader is not in a chair, relaxed, reading your prose for understanding. They are standing, stressed, possibly with one hand occupied, looking back and forth between your text and a physical object, and they want exactly one thing: to be done. Every word you write either gets them closer to done or makes them angrier. There is no third option.

This chapter is about writing that tells people how to do things—user manuals, how-to guides, standard operating procedures (SOPs), onboarding documents, the steps taped inside a supply cabinet, the README that tells a new engineer how to set up the project. It is the most-used and least-respected genre in technical communication. Nobody admires a great set of instructions; they just succeed at the task and move on. But everybody remembers the bad ones—the furniture assembly guide with the missing step, the software tutorial that assumed a tool you didn't have installed, the SOP so vague that two people did the job two different ways and one of them was wrong. The cost of bad instructions is not aesthetic. It is wasted time, broken equipment, failed onboarding, inconsistent work, and, in the wrong setting, real injury. This is theme 2 (audience is everything) at its most concrete: your audience is not a reader. Your audience is a doer. And it is theme 5 (structure serves the reader, not the writer) made physical, because the structure of a procedure is the structure of the task, performed in the order a body performs it.

Here is the threshold this chapter asks you to cross, and it reframes everything: the reader of instructions is not reading—they are doing. They are not consuming your document; they are using it as a tool while their attention is on something else. Once you internalize that, the rules of this chapter stop being arbitrary style preferences and become obvious consequences. One action per step? Because a doer executes one action, then looks back at the page. Warning before the step? Because a warning after the dangerous action is a warning that arrives too late. Test it on a beginner? Because you—the person who knows how to do the task—are the worst possible judge of whether your instructions work. By the end of this chapter, you will be able to take a vague procedure that "everyone just knows" and rewrite it as numbered, testable steps that a person who has never done the task can follow to success—and you will be able to test those steps and find the hidden step you assumed.

In this chapter, you will learn to:

• Write a procedure as numbered steps, one action per step, in the imperative mood and in the exact order the reader will perform them.
• Place warnings, cautions, and notes where they actually protect the reader—before the step, not after—and choose the right signal word for the level of risk.
• Structure instructions for the reader who will not read sequentially: the one who skips the introduction and jumps straight to step 7.
• Write troubleshooting sections and annotated screenshots that solve the problem the reader actually has.
• Test your instructions on "someone who has never done this," find the assumed steps, and revise.

📗 Software/CS track: This is the foundation for everything in Part V. The setup instructions in a README (Chapter 25) and the step-by-step tutorial (Chapter 26) are this chapter applied to software, where the "someone who has never done this" test becomes "clone the repo on a clean machine and follow your own README." Pay special attention to §22.2 (numbered steps), §22.6 (non-linear readers), and §22.8 (testing). 📘 Business/Professional track: SOPs and onboarding documents are how organizations make work repeatable and survivable when people leave. A good procedure is institutional memory you can hand to a new hire. Prioritize §22.2, §22.3 (warnings/notes), and §22.7 (SOPs and onboarding)—the genres you'll write most.

22.1 The Reader Is Doing, Not Reading

Start with the failure, because the failure teaches the principle. Here is a procedure of the kind that exists in millions of workplaces—written by someone who knows the task perfectly, for someone who does not.

❌ Before (a vague procedure — fictional but realistic): To process a refund, first you'll want to make sure the return has been received and inspected, and assuming everything checks out, go ahead and pull up the order in the system and verify the customer's information before initiating the refund through the payment processor, making sure to note the reason code and that the amounts match. Refunds over $500 need approval. Then update the order status and let the customer know.

Read that as a reader and it seems fine—it's a grammatical paragraph, it covers the task, nothing is factually wrong. Now read it as a doer, standing at the system with a returned package and a customer waiting. Where do you start? "First you'll want to make sure the return has been received and inspected"—received and inspected by whom, checked how, and what does "everything checks out" mean? Which payment processor, and where is the refund button? When does the over-$500 approval happen—before you start, or after, and who approves it, and how do you ask? The paragraph is a description of the task written by someone remembering it, not a set of instructions someone can execute. A doer cannot use it without already knowing how to do it—which defeats the entire purpose.

Now the same task, rewritten for a doer:

✅ After (testable numbered steps):

Before you begin: Confirm the returned item is logged as Received and Inspected: Pass in the Returns queue. If it is not, stop—the warehouse team must complete inspection first.

⚠️ Refunds over $500 require manager approval before you begin. Request approval in the #refund-approvals channel and wait for a ✅ before continuing.

1. In OrderTool, search for the order by order number or customer email.
2. Open the order and confirm the customer name and email match the return request.
3. Click Issue Refund.
4. In the refund dialog, select the reason code that matches the return reason.
5. Confirm the refund amount matches the item's purchase price (including tax). If the amounts differ, stop and escalate to your team lead.
6. Click Confirm Refund. Wait for the green "Refund submitted" banner.
7. Set the order status to Refunded.
8. Send the customer the "Refund Processed" email template from OrderTool.

Why it's better: Every sentence in the "before" was about the task; every line in the "after" is an action the reader takes. The steps are numbered, so a doer can look away to perform step 3, then return their eyes to the page and instantly find their place at step 4—something a paragraph makes impossible. Each step is one action. The approval requirement moved to the top, before step 1, because that's when the reader needs to know it (asking for approval after you've started the refund is too late). Vague phrases became checkable conditions: not "make sure everything checks out" but "confirm it's logged as Received and Inspected: Pass." The reader no longer needs to already know the task. That is the entire difference between a description and an instruction.

🚪 Threshold Concept: The reader is doing, not reading.

How novices write instructions: they write a description of the procedure as they remember performing it—a smooth, connected paragraph aimed at a reader sitting and absorbing. They optimize for completeness and flow ("and then, assuming everything is fine, you'll go ahead and…"). They assume the reader will read the whole thing first, understand the task, and then go do it. They write for comprehension.

How instructions actually get used: the reader does not read the document and then act. They read one step, perform it with their attention on the object (a machine, a screen, a patient, a server), then glance back to find the next step. Their working memory is full of the task, not your prose. They skip your introduction. They start partway down when they think they already know the beginning. Reading is an interruption to doing, and they want each interruption to be as short as possible. So instructions are not prose to be understood—they are a tool to be operated, one action at a time, by a person whose mind is elsewhere.

Once you cross this threshold, the rules of the chapter become inevitable rather than stylistic. One action per step, imperative verbs, parallel structure, warnings before the danger, white space the eye can find its place in—none of these are about elegance. They are about a stressed person executing one action and then finding the next one fast. You stop writing to be read and start writing to be used.

The shift is from describing to directing. A description tells the reader what the process is. An instruction tells the reader what to do. The grammar of the two is different (description narrates; instruction commands), the structure is different (description flows; instruction steps), and the test of success is different. A description succeeds if the reader understands. An instruction succeeds only if the reader can do the thing—and the only way to know that is to watch someone try.

🔄 Check Your Understanding A coworker writes: "Setting up the test environment is straightforward—you basically just install the dependencies, configure your environment variables, and run the migration, then you should be good to go." Why will this frustrate a new hire even though it's accurate?

Answer

It's a description of the task by someone who already knows it, not instructions someone can execute. "Install the dependencies"—which command, with what tool? "Configure your environment variables"—which ones, to what values, in which file? "Run the migration"—what's the exact command, and how do you know it worked? "You should be good to go"—how do you verify? A new hire can't act on any of it without already knowing how. The reader is a doer who needs each action specified, not a reader who needs the gist. The words "straightforward" and "basically just" are a tell: they signal the writer is collapsing several steps they perform automatically into one phrase—the curse of knowledge, hiding the very steps the beginner needs.

22.2 The Numbered Step: One Action, Imperative, In Order

The numbered step is the workhorse of procedural writing, and it has three rules that come straight from the threshold concept. A doer performs one action and looks back; so each step is one action. A doer needs to be told to act, not informed about acting; so each step is in the imperative mood. A doer performs the task in a sequence; so the steps run in performance order. Get these three right and most of the genre takes care of itself.

One action per step

A step is the unit a reader executes between glances at the page. If you cram three actions into one step, the reader performs the first, looks back, and can't tell how far they got. Split them.

❌ Before: 3. Open the valve cover, remove the old filter and dispose of it according to local regulations, then insert the new filter making sure the arrow points toward the engine and close the cover.

✅ After: 3. Open the valve cover. 4. Remove the old filter. 5. Dispose of the old filter according to your local regulations (see Appendix B). 6. Insert the new filter with the arrow pointing toward the engine. 7. Close the valve cover.

Why it's better: Five distinct physical actions are now five steps a reader can perform and check off one at a time. In the "before," a reader who installs the filter backward has no clean place to discover the error; in the "after," step 6 isolates the one thing most likely to go wrong (arrow direction) and gives it its own line, where it's hard to miss. The reader always knows exactly where they are.

The honest exception: very tightly coupled micro-actions can share a step when splitting them would be pedantic ("Press and hold the reset button for five seconds"—one step, even though "press" and "hold" are technically two verbs, because they're one continuous motion). The test is the glance: if a reader would naturally pause and look back at the page between two actions, they're two steps. If not, one.

Imperative mood

The imperative mood is the grammar of command: "Click Save," "Remove the cover," "Wait for the green light." It addresses the reader as you (implied) and tells them to act. It is the correct mood for nearly every step in nearly every procedure, and the most common failure of amateur instruction-writers is drifting out of it.

❌ Before (drifting moods): 1. The user should first locate the power button. 2. You'll want to press and hold it for three seconds. 3. The device will then begin to power on. 4. It is necessary to wait until the logo appears.

✅ After (consistent imperative): 1. Locate the power button on the right edge. 2. Press and hold the power button for three seconds. 3. Wait until the logo appears.

Why it's better: Three different non-imperative constructions ("the user should," "you'll want to," "it is necessary to") each add words and soften a command into a suggestion. Step 3 in the "before"—"the device will then begin to power on"—isn't even an instruction; it's a description of what the machine does, mixed into a list of things the reader does, which is confusing because the reader can't tell what they're supposed to do. The "after" cuts that line (the reader doesn't need to be told the device powers on; that's obvious from the logo appearing) and keeps every remaining step a clean command. This is the conciseness discipline from Chapter 3 applied to steps: "you'll want to press" is "press" with three inert words in front of it. Free the verb; lead with it.

🔍 Why Does This Work? Why is the imperative ("Press the button") clearer than the seemingly more polite "You'll want to press the button" or "The user should press the button"? Think before reading on.

Because the imperative puts the action in the first, strongest position and removes everything between the reader and the verb. "You'll want to press" forces the reader to parse a prediction about their desires before reaching the actual instruction; "the user should" adds a layer of third-person distance (am I "the user"?) plus a hedge ("should"—or what if I don't?). A doer scanning back to the page wants the verb now. The imperative is also unambiguous about who acts: it's you, the reader, right now. "The device will power on" describes the machine; "press the button" directs the human—and in a list of steps, the reader must instantly know which lines are their job. The imperative marks every one of the reader's actions with the same grammatical shape, so the eye learns the pattern and moves fast. Politeness isn't the goal; getting the reader to done is, and the imperative is the most direct route.

Performance order

Steps must appear in the exact order the reader performs them. This sounds obvious, yet it's violated constantly, because the writer knows the whole task and mentions things when they come to mind, not when the reader needs them.

❌ Before: 1. Run npm run build to compile the project. (Make sure you've installed Node 18 or later first.)

✅ After: 1. Confirm Node 18 or later is installed: run node --version. If the version is below 18, install Node 18 before continuing (see Prerequisites). 2. Compile the project: run npm run build.

Why it's better: In the "before," the prerequisite (install Node first) is mentioned inside the step that depends on it—a reader on Node 16 runs the build command, it fails with a cryptic error, and only then reads the parenthetical telling them what they should have done first. The information arrived after it was useful. The "after" puts the check before the action. A rule that follows directly: anything the reader must do or have before a step belongs before that step—as an earlier step, a prerequisite, or (for hazards) a warning, never as an aside tucked into the step it gates.

This is also why a procedure needs a prerequisites section ("Before you begin") at the top: tools, permissions, materials, and conditions the reader must have in hand before step 1. Nothing is more demoralizing than reaching step 6 and learning you needed a part, a password, or a 30-minute approval you don't have. List them up front so the reader can assemble everything, then proceed without interruption.

✏️ Try This Take the last set of instructions you wrote or received—even an informal "here's how to do X" message. Number the steps if they aren't numbered. Then check each step against the three rules: Is it exactly one action? Is it an imperative command (starts with a verb the reader performs)? Is anything mentioned after the point where the reader needed it? You'll almost always find at least one buried prerequisite.

[📍 Good stopping point — you now have the core mechanics: one action, imperative, in order. The next sections cover what wraps around the steps: warnings, the skipping reader, and screenshots.]

22.3 Warnings, Cautions, and Notes: Placement Is Everything

Some steps carry consequences—damaged equipment, lost data, physical injury, a result that can't be undone. The reader needs to know before they act. This is where procedural writing carries genuine weight, and where placement is not a style question but a safety one.

There is a near-universal hierarchy of signal words, formalized in standards used across hardware, medical devices, and industrial documentation (the ANSI Z535 family is the common reference). Use them consistently:

The distinction between these is not pedantry. If you label every aside a "Warning," readers learn that "Warning" means "minor tip" and ignore the one that matters. Reserve the strong words for real risk, so they keep their force. A Note is not a quiet Warning; it carries no hazard, and dressing a hazard as a Note ("Note: don't do this while the power is on") badly under-signals the danger.

Now the rule that matters most, the one the whole section is built around: a warning goes immediately before the step that triggers it—never after, never only at the top.

❌ Before (warning too late): 7. Disconnect the power cable from the unit. 8. Remove the four screws on the base plate. 9. Lift off the base plate. Warning: The capacitor can retain a dangerous charge. Do not touch the exposed terminals.

✅ After (warning before the danger): 7. Disconnect the power cable from the unit.

⚠️ Warning: Even with the power disconnected, the capacitor can retain a dangerous charge for up to two minutes. Do not touch the exposed terminals on the board. Wait two minutes after disconnecting power before continuing.

8. Remove the four screws on the base plate. 9. Lift off the base plate, keeping your fingers clear of the board.

Why it's better: In the "before," the reader learns about the dangerous charge after they've already lifted the plate and possibly touched the terminals—the warning arrives a step too late to do its job. A warning after the hazardous action is decoration; it documents the danger without preventing it. The "after" places the warning between the step that removes the protection (disconnecting power, removing the plate) and the exposure, so the reader reads it before they're at risk. It also does three things a good warning does: it names the specific hazard (charged capacitor, not "be careful"), it explains why (the charge persists even unplugged—countering the reader's reasonable assumption that "unplugged = safe"), and it says what to do (wait two minutes, keep fingers clear). "Be careful" is useless; "the capacitor holds a charge for two minutes—wait before touching the board" is a warning that works.

Three placement principles fall out of this:

• Hazard warnings: immediately before the triggering step. The reader must read the warning before they can perform the dangerous action.
• General cautions about the whole procedure: at the top, in the prerequisites. "This procedure involves working near a live circuit; do not attempt it without proper training" belongs before step 1—but also repeat the specific warning at the specific step, because the skipping reader (next section) never read your top matter.
• Notes: before or after the step, wherever they help. A Note that clarifies a step ("Note: older models label this 'Door C'") can sit right under the step. A Note has no urgency, so its placement is about helpfulness, not safety.

⚠️ Warning Never bury a safety-critical warning inside a step's sentence where a scanning reader will skip it. "Remove the panel (being careful of the sharp edge) and set it aside" hides the hazard mid-sentence. Pull it out into its own visually distinct warning block, before the step. The reader who skims—and they all skim—must be unable to miss it.

🔄 Check Your Understanding An SOP for a lab centrifuge lists, at the very top: "Caution: never open the lid while the rotor is spinning." The actual "open the lid" instruction is step 9, three pages later. Two things are wrong here. What are they?

Answer

(1) Placement: the warning is only at the top, three pages from the step it governs. A reader who jumps to step 9 (or simply forgets the top matter by the time they get there) opens the lid without seeing the warning. The specific hazard warning must be repeated immediately before step 9, where the action happens. (2) Signal word: "never open the lid while spinning" on a centrifuge is a serious injury risk (a spinning rotor opened to the air can cause severe harm), so "Caution" under-signals it—Caution is for minor injury or equipment damage. This should be a "Warning" (or "Danger," depending on the rotor speed and the standard in use). Reserving strong signal words for real risk is exactly what keeps them credible.

22.4 Annotated Screenshots and Visuals: Show, Don't Just Tell

For software, hardware, and any task with a physical or on-screen reference, a picture often does what a sentence cannot: it shows the reader exactly where to look. "Click the gear icon in the top-right corner" is good; the same instruction beside a screenshot with the gear icon circled is better, because the reader matches the picture to their screen instantly instead of parsing your spatial description and hunting. But a bad screenshot is worse than none—it adds clutter, goes stale, and misleads. A few principles keep visuals useful.

Annotate; don't just paste. A raw, full-screen screenshot drops the reader into a sea of interface and makes them find the one element you mean. The value is in the annotation: a circle, arrow, box, or number pointing to the specific thing. A callout (a numbered marker on the image that corresponds to a numbered step or caption) ties the picture to the words.

❌ Before: "Open the settings menu and find the notification preferences, then toggle off email alerts." — followed by a full, un-annotated screenshot of the entire settings page with forty options visible.

✅ After: "1. Click the gear icon (Figure 22.1, callout 1). 2. In the left menu, click Notifications (callout 2). 3. Toggle Email alerts to Off (callout 3)." — beside a screenshot cropped to the relevant panel, with three numbered circles matching the three steps.

Why it's better: The annotated, cropped image points to exactly the three elements the three steps name, and the callouts (1, 2, 3) map picture to step. The reader's eye goes straight to the target. The un-annotated full-page shot, by contrast, makes the reader do the finding work the picture was supposed to do for them.

Crop to what matters. Show the relevant panel, not the whole 27-inch monitor shrunk to thumbnail size. Cropping is the visual equivalent of cutting words (Chapter 3): remove everything that isn't carrying information.

Beware staleness. Screenshots are the highest-maintenance part of any documentation, because interfaces change and a screenshot from two versions ago shows buttons that no longer exist—actively misleading the reader. Two defenses: (1) screenshot only what's stable and necessary, so you have fewer images to update; and (2) keep the text instruction authoritative and the image supporting, so that if the screenshot drifts, the words still get the reader there. Never write "click the button shown below" with no name—if the image goes stale or fails to load, the instruction is now useless. Always name the element in text ("click Save"); let the image confirm, not replace, the words.

💡 Tip Caption every figure with what the reader should see or do, not just what it is (the interpreting-caption skill from Chapter 9, applied to procedures). Not "Figure 22.1: The settings page." Instead: "Figure 22.1: Toggling email alerts off—the gear icon (1), Notifications (2), and the Email alerts switch (3)." The caption alone should orient a reader who can't see the image well.

Accessibility of visuals (and procedures generally)

Per the book's accessibility standard, an image that carries instructional information must not be the only way to get that information. Some readers use screen readers; some have images turned off; some print in grayscale where your red circle vanishes. So:

• Always provide the steps in text. The numbered text steps are the real instruction; the screenshot supports them. A reader who can't see the image must still be able to complete the task from the words alone. (This is also why "click the third button from the left" is fragile and "click Export" is robust—the latter doesn't depend on sight or a stable layout.)
• Write alt-text that conveys the instruction, not just the scene. Alt-text for a procedural screenshot should say what the reader needs: "The Notifications settings panel with the Email alerts toggle switched off"—not merely "screenshot of settings."
• Don't rely on color or position alone in annotations. Pair a colored circle with a number or label, so a grayscale or color-blind reader still gets the reference (the color-independence rule from Chapter 10). "The red button" fails for ~1 in 12 men; "the Delete button (red)" works for everyone.

Procedural writing is, in a sense, the most accessibility-sensitive genre in this book: the reader is often under stress, sometimes one-handed, sometimes reading by ear, and a single inaccessible step blocks the whole task. The plain-language defaults this book has taught throughout—short sentences, concrete words, one idea at a time—aren't just nice here; they're what lets the widest range of doers actually do the thing.

22.5 Writing for the Reader Who Skips Around

Here is a fact about instructions that you must design around: nobody reads them front to back. They skip the introduction. They jump to the section that names their problem. They start at step 7 because they think they already know steps 1 through 6. They land on your page from a search engine, mid-procedure, with no context. If you write instructions assuming a reader who starts at the top and proceeds in order, you've written for a reader who does not exist. This is theme 5 again—structure for how they actually read—and for procedures, "how they read" means non-linearly, under time pressure, entering anywhere.

Several techniques make instructions survive a non-linear reader.

Make every section self-locating with informative headings. The reader scanning for their task needs headings that name tasks, not vague labels—exactly the informative-header lesson from Chapter 4. Not "Section 3" or "Additional Configuration," but "How to Reset Your Password" and "Connecting to the VPN from Off-Campus." A reader should be able to find their task by running their eye down the headings, the way they scan any document. Task-named headings are how a skipping reader finds the right place to start.

Make steps survive being entered mid-stream. A reader who jumps to step 7 should not be sunk by a pronoun that refers back to step 4. "Now drag it into the folder" is broken for anyone who didn't read the step that named it. Prefer "Drag the config.json file into the /settings folder." Repeating the noun feels redundant to you, who read every prior step; to the reader who teleported in at step 7, the repeated noun is the only thing keeping them oriented. (This is the "vague this/it with no referent" problem from Chapter 6, made worse by non-linear reading.)

Repeat critical warnings at the point of use. As §22.3 stressed: a warning that lives only in the introduction protects no one who skipped the introduction. If step 9 is dangerous, the warning goes at step 9, even if you also stated it up front. Redundancy that you'd cut from prose is correct in safety-critical procedures, because you cannot assume the reader saw the earlier instance.

Provide an entry map for long procedures. A table of contents, a "Which section do I need?" decision list, or a short index lets the reader self-route to their task. For a long manual, a one-line "If you want to X, go to section Y" router at the top saves the reader from reading anything they don't need.

❌ Before (assumes linear reading): Section heading: "Step 7 (continued)." Step text: "Set this value to match the one you noted earlier, then save."

✅ After (survives a mid-stream entry): Section heading: "Configuring the Database Connection." Step text: "7. In the DATABASE_URL field, enter the connection string from your hosting dashboard (the value you copied in step 4; it begins with postgres://). Click Save."

Why it's better: The vague heading "Step 7 (continued)" tells a scanning reader nothing about what task it serves; "Configuring the Database Connection" lets them find it. The vague "this value" and "the one you noted earlier" assume the reader did the earlier steps; the revised step names the field, names what to enter, and gives a recognizable signpost ("begins with postgres://") so a reader who skipped step 4 can still identify the right value. The step is now robust to being read on its own.

🧩 Productive Struggle Before reading the resolution: you're writing a help article titled "How to Export Your Data." Your analytics show most readers arrive directly from a Google search for "export data from [product]," landing on this page with zero context—they haven't read your getting-started guide, they don't know your terminology, and many are mid-panic because they're trying to leave or back up. List three specific things you'd change about how you write the steps, given that the reader arrives cold and anxious, versus how you'd write them for someone reading your manual cover to cover.

One good answer

(1) Open with prerequisites and scope, not story. State what they need (an admin account? a paid plan?) and what the article covers in the first two lines, because they have no context and will bail if it's not obviously the right page. (2) Name everything explicitly; assume no prior terminology. Don't reference "your workspace" or "the dashboard you set up earlier"—the cold reader never set anything up in your narrative. Say exactly where each element is. (3) Put the actual steps first and the explanation after (or in expandable detail). An anxious reader wants the steps immediately; lead with the numbered procedure, and tuck the "why" and edge cases below for those who want them. Bonus: (4) repeat any warning (e.g., "exporting does not delete your data" or "the export link expires in 24 hours") right at the relevant step, since they didn't read your top matter. For the cover-to-cover reader you could lean on earlier context and shared terms; for the cold searcher, every step must stand alone.

22.6 Troubleshooting Sections: For When It Doesn't Work

Instructions tell the reader what to do when everything goes right. A troubleshooting section tells them what to do when it doesn't—and since something always goes wrong for some reader, troubleshooting is not optional padding; it's where instructions earn their keep. A reader hits an error, the happy-path steps have run out, and they are one bad minute away from giving up. A good troubleshooting section catches them.

The dominant pattern is symptom → cause → fix, organized by what the reader observes, because that's all they have. The reader doesn't know the cause—if they did, they wouldn't need you. They know the symptom: an error message, a light that won't turn green, a screen that won't load. So index your troubleshooting by symptom, in the reader's words.

❌ Before (organized by the system's internals): "Error code 0x0000007B indicates a boot device inaccessibility condition arising from storage controller configuration mismatches."

✅ After (organized by what the reader sees and can do): Symptom: The installer stops with a blue screen and the code 0x0000007B. This usually means the installer can't find the drive. Try these in order: 1. Confirm the drive is plugged in and shows up in the BIOS (press F2 at startup → Storage). If it's not listed, reseat the cable and try again. 2. In the BIOS, set the storage mode to AHCI (Storage → SATA Mode). The most common cause of this error is the mode being set to RAID when the installer expects AHCI. 3. If the drive still doesn't appear, test it in another machine to rule out a failed drive.

Why it's better: The "before" describes the error in the system's terms and gives the reader nothing to do. The "after" leads with the symptom in the reader's words ("blue screen and the code 0x..."), tells them in one plain sentence what it usually means, then gives ordered actions from most-likely-and-easiest to least—the reader tries the common fix first and only escalates if needed. It's instructions, not a diagnosis: every line is something the reader can perform.

Principles for a troubleshooting section that works:

• Index by symptom, in the reader's language. "The light blinks red and won't connect," not "Authentication handshake failure." The reader searches with the symptom; meet them there.
• Order fixes by likelihood and ease. Put the common, cheap fix first ("Is it plugged in? Is the cable seated?"). Don't send the reader to disassemble the unit before checking the power switch.
• One probable cause and one concrete fix per symptom—then escalate. Keep each entry actionable. If the listed fixes don't work, tell the reader exactly where to go next ("contact support with your order number and the exact error text").
• Anticipate the predictable failures. You learn these from testing (next section) and from support tickets. The errors real users hit—not the exotic ones—are what the troubleshooting section is for.
• A short FAQ is troubleshooting's cousin. The questions readers actually ask ("Can I undo this?" "Why didn't I get the email?") belong somewhere findable; an FAQ catches the doubts a strict symptom list doesn't.

🔄 Check Your Understanding Why should a troubleshooting section be organized by symptom rather than by cause, even though the writer naturally thinks in terms of causes?

Answer

Because the reader only has the symptom. They observe an error message, a failed result, a light that won't change—they do not know the underlying cause (if they did, they could fix it themselves and wouldn't be reading). The writer knows the system's internals and is tempted to organize by cause ("storage controller mismatch"), but a reader can't find their problem under a cause they can't see. Organizing by observable symptom, in the reader's own words, lets them locate their situation and then walk the cause/fix that follows. It's the audience principle (Chapter 2): structure the information around what the reader knows, not what you know.

22.7 SOPs and Onboarding: Procedures as Institutional Memory

Two high-value workplace genres are just procedures with a particular purpose: the standard operating procedure (SOP) and the onboarding document. Both exist so that a task can be done the same way, correctly, by someone who isn't the expert—including the version of your team that exists after the expert leaves. A good SOP is institutional memory you can hand to a stranger.

SOPs make work repeatable and auditable. The same task, done by different people on different days, should produce the same result—that's the entire point. So an SOP carries a bit more scaffolding than a casual how-to:

• Purpose and scope: what the procedure is for and when it applies (and when it doesn't).
• Roles/responsibilities: who does each part, who approves, who is notified.
• Prerequisites: required access, tools, training, conditions.
• The numbered procedure: the same one-action-imperative-ordered steps as any instruction.
• Warnings/compliance notes: placed at the step, per §22.3.
• A revision record: version, date, owner—because an SOP that's out of date is worse than none, and someone must own keeping it current.

The discipline that makes an SOP work is removing the ambiguity that lets two people do it differently. "Review the report and approve if it looks good" is not an SOP—"looks good" is undefined, so two reviewers apply two standards. "Confirm the totals match the source file and that no line item exceeds $10,000; if both are true, mark Approved; otherwise, route to Finance" is an SOP, because any two people following it reach the same decision. The test of an SOP is reproducibility across people: would two readers, following only the document, do the same thing? If a step leaves room for "it depends on judgment," either specify the judgment or name who makes the call.

Onboarding documents are procedures for becoming productive—how to set up your accounts, your environment, your access; who to ask for what; the steps to first contribution. Their special hazard is the curse of knowledge in its purest form: the person writing the onboarding doc has been here for years and has forgotten every implicit thing a newcomer doesn't know. They write "just request access to the usual systems" and the new hire has no idea what "the usual systems" are or how to "request access." The fix is structural and is the subject of the next section: you cannot write a good onboarding doc from memory. You have to watch a new person use it, because only a newcomer can see the steps you've gone blind to. The single best time to write or fix onboarding documentation is the week you onboarded, while the gaps are still visible to you.

📐 Project Checkpoint: User Documentation (Portfolio Piece 3)

This chapter is where your portfolio's user documentation / instructions piece (Piece 3 of the seven) comes to life. You've been building toward documents that serve a reader; now you build one that serves a doer.

Recall the prior increment. Across Part II you learned to make documents clear (Chapter 3), structured for scanners (Chapter 4), and visually navigable (Chapter 10). Your portfolio so far leans toward documents people read. This piece is different in kind: it's a document people use while doing something else.

This chapter's addition — draft a real procedure. Choose a task you genuinely know how to do and that a beginner plausibly doesn't: setting up a development environment, operating a piece of lab or shop equipment, completing a multi-step form or workflow, assembling or configuring something, or an SOP for a recurring task at work. Write it as a complete set of instructions with all the parts this chapter covers: - a title that names the task and an audience/scope line, - a "Before you begin" prerequisites block (tools, access, materials, conditions), - numbered steps: one action each, imperative, in performance order, - at least one warning, caution, or note placed correctly (before the step it governs), - a short troubleshooting section (at least three symptom → fix entries), - and at least one annotated visual or a clearly-described figure (with alt-text), if the task has a visual reference.

Aim for a procedure a stranger could follow. Do not polish it to a shine yet—the next step is to break it.

Preview the next increment. In §22.8 you'll test this draft on someone who has never done the task, watch where they stall, and revise. That test-and-revise pass is where this piece actually becomes good—and it's the same revise-from-real-feedback discipline (theme 4) you'll carry into Chapter 25 (READMEs) and Chapter 26 (tutorials), where "test it" becomes "run your own setup steps on a clean machine."

22.8 Testing Your Instructions: The "Someone Who Has Never Done This" Test

Here is the most important idea in the chapter, and the one writers resist most: you cannot evaluate your own instructions, because you already know how to do the task. Every step you wrote makes sense to you. The step you skipped—the one you do so automatically you forgot it exists—is invisible to you. The term that's obvious to you is jargon to a beginner. You are, by virtue of your expertise, the single worst judge of whether your instructions work. This is the curse of knowledge (Chapter 2) in its most operational form, and there is exactly one reliable cure: give your instructions to someone who has never done the task, watch them try, and say nothing.

The test, precisely:

1. Find a real beginner—someone who genuinely doesn't know the task, ideally close to your actual audience. Not the expert next to you who'll fill gaps from their own knowledge.
2. Give them only the instructions. No verbal coaching, no "oh, you also need to…". The document has to stand alone, because in the real world you won't be there.
3. Watch them, and stay silent. This is the hard part. When they stall, when they do step 4 wrong, when they can't find the button—do not help. Their stall is the data. Every place they pause, backtrack, ask "wait, where?", or do the wrong thing is a defect in your instructions, not in them.
4. Write down every stall. Where exactly did they hesitate? What did they misread? What step did they perform in a way you didn't intend? What did they have to ask?
5. Fix the instructions, not the tester. Each stall maps to a revision: a missing step to add, a vague phrase to specify, a warning to move earlier, a term to define, a screenshot to annotate.

This is usability testing for documents, and it is the same idea as Chapter 12's "you are not the best judge of your own writing"—but with teeth, because the failure is observable in real time. You don't have to argue about whether the instructions are clear; you watch a human being fail to follow them, and the argument is over.

What the test reliably exposes:

• The assumed step. The action you perform automatically and never wrote down—"plug it in first," "save before running," "make sure you're on the right branch." This is the single most common defect, and it's nearly impossible to find any other way, because your own mind supplies the missing step without telling you. The tester, lacking your automation, simply stops.
• The undefined term. A word that's transparent to you and opaque to them ("the staging environment," "the rear access panel," "the usual systems").
• The ambiguous instruction. A step that you read one way and they read another—revealing that the step had two meanings and you only saw one.
• The wrong order. A prerequisite you mentioned too late, caught when the tester does the dependent step and it fails.

❌ Before (an assumed step, invisible to the author): 1. Open the configuration file in your editor. 2. Change debug to false. 3. Restart the service. The change is now live.

✅ After (the assumed step, surfaced by a tester who stalled): 1. Open the configuration file config/app.yaml in your editor. 2. Change debug: true to debug: false. 3. Save the file. (The tester changed the value but never saved—so the restart loaded the old config and "nothing happened." This step was missing.) 4. Restart the service: run sudo systemctl restart appserver. 5. Confirm the change took effect: the startup log should no longer show DEBUG MODE ON.

Why it's better: The original "save the file" step lived only in the author's head—they save by reflex and never noticed it was an action. A tester who changed the value, restarted, and saw no change exposed the gap instantly. The revision adds the missing save step, and (prompted by the same test) specifies the file path the tester couldn't guess, the exact restart command, and a way to verify success—so the next reader confirms it worked instead of wondering. One observed stall produced four improvements. That return is why testing is non-negotiable.

🔍 Why Does This Work? Why can a complete stranger find flaws in your instructions that you—the expert who wrote them and knows the task cold—genuinely cannot find by re-reading? Think before reading on.

Because the flaws are gaps between what you know and what the instructions say, and you can't perceive that gap from inside your own knowledge. When you re-read your instructions, your mind silently fills every gap with what you already know: you read "restart the service" and your brain supplies "after saving, of course," so the missing save step is invisible to you—you literally cannot see its absence, because you never experience the absence. The beginner has no knowledge to fill the gap with, so they hit it head-on and stop. Their ignorance is precisely the instrument that detects your assumptions: they fail exactly where the instructions assume knowledge they don't have, which is exactly where the instructions are defective. You can't test your instructions against your own knowledge because that knowledge is the contamination. You need a mind that lacks it. (And no expert reviewer fully substitutes—they have their own knowledge to paper over your gaps with. A genuine beginner is the clean test.)

If you cannot recruit a tester, the partial substitutes, in rough order of usefulness: (1) follow your own instructions literally and stupidly, doing exactly and only what each step says, on a clean setup (a fresh machine, a reset device)—pretend you've never seen the task; (2) wait a day and re-read, so the automatic gap-filling weakens; (3) read each step aloud and ask "could someone who knows nothing do only this and succeed?"; (4) have any colleague try, even a knowledgeable one (imperfect, but they may still trip on something). None match watching a real beginner—but all beat shipping untested.

🪞 Learning Check-In Pause and reflect on your own writing habits. When you've written instructions before—a how-to message, a handoff doc, setup steps for a teammate—did you test them on anyone, or did you write them, give them a quick read, and send? Be honest: how often have your "obvious" instructions generated a follow-up question that turned out to be a step you'd assumed? The skill this chapter teaches is partly humility—accepting that your expertise disqualifies you as the judge of your own instructions—and partly a habit: build "watch one person try it" into how you ship anything procedural. Which of your current or upcoming documents could you put in front of a beginner this week?

22.9 Common Mistakes & Practical Considerations

The errors below are the ones that recur across user manuals, SOPs, onboarding docs, and how-to articles. Most trace back to the same root: writing for a reader who understands, instead of a doer who must act.

The assumed step. Covered at length in §22.8, but it tops the list because it's the most common and the most damaging. You perform some action automatically—save, plug in, log in, switch to the right directory—and never write it down. The reader stops dead. The only reliable defense is testing on a beginner.

Description instead of instruction. Writing about the task ("the system will then validate the input") instead of telling the reader what to do ("click Validate"). If a step doesn't start with (or quickly reach) a verb the reader performs, it's probably a description that snuck into a procedure.

The mood drift. Sliding out of the imperative into "you should," "the user will want to," "it is necessary to." Each adds words and softens a command. Fix: start steps with the action verb.

Steps that bundle. Three actions in one step, so the reader can't track their place. Split until each step is one glance-and-do unit.

Warnings in the wrong place (or wrong word). A hazard warning after the dangerous step, or only at the top where skippers miss it, or labeled "Note" so it under-signals. Hazard warnings go immediately before the triggering step, in the right signal word, repeated at the point of use.

The vague condition. "If everything looks good, proceed." "When it's ready." "Once the system is properly configured." These push the judgment back onto a reader who lacks the expertise to make it. Specify the checkable condition: what should they see, what values, what state.

Untested screenshots that have gone stale. An image showing a button that no longer exists actively misleads. Keep text authoritative, screenshots minimal and current, and never write "click the button below" with no name.

Writing for a linear reader. Pronouns that depend on earlier steps, warnings only in the intro, headings that don't name tasks. The real reader enters at step 7 from a search result. Make steps and sections survive being read out of order.

No troubleshooting and no verification. Instructions that cover only the happy path abandon the reader at the first error. And steps that don't tell the reader how to confirm success leave them unsure whether it worked. Add a troubleshooting section and, where it matters, a "you'll know it worked when…" check.

The honest "it depends." How much detail? It depends on the audience's expertise and the cost of error. An SOP for a nuclear procedure and a quick "how to book a meeting room" guide are both procedures, but the first specifies everything and warns heavily because the cost of a wrong step is catastrophic, while the second can assume basic competence and skip the hand-holding. Calibrate to who is doing the task and what happens if they get it wrong. When the cost of error is high or the audience is true beginners, over-specify; when the reader is competent and the stakes are low, respect their time and don't belabor the obvious. The audience question (Chapter 2) decides the granularity.

📚 Going Deeper: Minimalism and "guaranteed success" A well-known school of instructional design (often called minimalist documentation, associated with John Carroll's research) argues that adults learning by doing skip most of what you write, want to start acting immediately, and learn best from short, task-focused, error-tolerant instructions rather than long comprehensive manuals. Two practical takeaways: (1) get the reader doing fast—lead with the steps, not pages of background—and (2) support recovery from error (the troubleshooting mindset), because learners will make mistakes and the question is whether your instructions help them recover. The tutorial chapter (Chapter 26) builds on this with the idea that a good tutorial guarantees a success experience. For procedures, the minimalist lesson is: respect that the reader wants to act, not read—give them the shortest path to done that still keeps them safe and correct.

Frequently Asked Questions

How do I write step-by-step instructions that people can actually follow?

Write each step as one action in the imperative mood (start with the verb the reader performs: "Click Save," "Remove the cover"), in the exact order the reader does the task. Put prerequisites ("Before you begin") and hazard warnings before the steps they affect. Name things explicitly instead of using vague pronouns, since readers skip around. Then do the part most people skip: test the instructions on someone who has never done the task, watch where they stall, and fix those spots. The stalls are your defects.

Where do warnings and cautions go in a procedure?

A hazard warning goes immediately before the step that triggers it, never after (a warning after the dangerous action arrives too late) and never only at the top (readers who jump to step 9 miss it). State the specific hazard, why it's dangerous, and what to do—"the capacitor holds a charge for two minutes; wait before touching the board," not "be careful." Use signal words by severity: Danger (will cause serious injury), Warning (could), Caution (minor injury or equipment/data damage), Note (helpful info, no hazard). Don't label a tip "Warning" or a hazard "Note."

What's the difference between instructions and a standard operating procedure (SOP)?

An SOP is a procedure with extra scaffolding so a task is done the same way by anyone: a purpose/scope statement, roles and responsibilities, prerequisites, the numbered steps, compliance notes, and a revision record with an owner. The defining discipline is removing ambiguity that would let two people do the task differently—replace "approve if it looks good" with a checkable rule any two readers would apply identically. The test of an SOP is reproducibility across people.

How do I test my own instructions if I can't find a tester?

Watching a real beginner is best, but if you can't, the substitutes are: (1) follow your own steps literally and only—doing exactly what each says and nothing more—on a clean setup (fresh machine, reset device), pretending you know nothing; (2) wait a day so your automatic gap-filling weakens, then re-read; (3) read each step aloud and ask "could someone who knows nothing do only this and succeed?"; (4) have any colleague try it. None fully replace a genuine beginner—your expertise is exactly the contamination—but all of them beat shipping untested.

Why do my "obvious" instructions confuse people?

Because of the curse of knowledge: you do parts of the task so automatically that you no longer notice them, so you leave them out—the "save the file," "plug it in," "switch to the right directory" steps that are invisible to you and essential to a beginner. When you re-read, your mind silently fills every gap with what you already know, so you can't see the gaps. A beginner has no knowledge to fill them with, so they stop exactly where your instructions assume too much. That's why you must watch a real first-timer try.

Chapter Summary

Key Takeaways

• The reader is doing, not reading. They use instructions as a tool while their attention is on a task—executing one action, then glancing back. Every rule of the genre follows from this.
• Numbered steps: one action, imperative, in order. One action per step (so the reader can track their place), the imperative mood (lead with the verb they perform), in exact performance order (with prerequisites up front).
• Warnings go before the step they govern—never after (too late), never only at the top (skippers miss it). Use the right signal word; name the hazard, the why, and the what-to-do.
• Readers skip around. Write headings that name tasks, steps that survive being entered mid-stream (no orphan pronouns), and warnings repeated at the point of use.
• Troubleshooting catches the reader when it fails. Organize by symptom in the reader's words, order fixes by likelihood and ease, and tell them where to escalate.
• Test on someone who has never done the task. Your expertise disqualifies you as the judge. Watch a beginner try, stay silent, write down every stall, and fix the instructions—not the tester.

Action Items

• Convert one description-style "how to" you've written into numbered, imperative, one-action steps.
• Add a "Before you begin" prerequisites block to it.
• Move any hazard warning to immediately before its step; check every signal word.
• Add a three-entry troubleshooting section organized by symptom.
• Recruit one beginner, watch them follow it silently, and revise from the stalls.

Common Mistakes

• Assumed steps (the invisible "save first"); description instead of instruction; mood drift; bundled steps; warnings placed too late or under-signaled; vague conditions ("if it looks good"); stale screenshots; writing for a linear reader; no troubleshooting and no success-check.

Decision Framework

Spaced Review

A few questions reaching back, to strengthen retention.

1. (From Chapter 4) Chapter 4's threshold concept is "the reader scans; they do not read." How does this chapter's threshold ("the reader is doing, not reading") extend that idea, and what new constraint does doing add that mere scanning doesn't?
2. (From Chapter 10) Chapter 10 taught the color-independence rule (never rely on color alone; pair it with a label or shape). Where in this chapter does that exact rule reappear, and why is it even more important in instructions than in ordinary documents?
3. (From Chapter 3, bridging) Chapter 3 taught you to "free the verb" by cutting nominalizations and leading with a strong verb. How is the imperative-mood rule for steps ("Press the button," not "you'll want to press the button") the same discipline applied to procedural writing?

What's Next

Chapter 23 (Collaborative Writing) tackles a problem this chapter quietly raised: procedures, SOPs, and onboarding docs are rarely written or maintained by one person—they're team documents that drift out of sync, accumulate conflicting edits, and need version control, a shared style, and a review workflow to stay coherent. You'll learn how to write with a team without losing your mind or your voice. Further out, this chapter is the foundation for Part V: Chapter 25 applies it to the README (where "test your instructions" becomes "run your own setup on a clean machine"), and Chapter 26 builds the full tutorial-versus-how-to distinction (Diátaxis) on top of the step-writing skills you just learned. The doer you wrote for here is the same reader who will follow your README and your tutorial—now you know how to write for them.

Practice: Exercises · Quiz Go deeper: Case Study · Case Study 2 Review: Key Takeaways · Further Reading