Technical Tutorial and How-To Template
Three documents and two sheets that state each step's expected result as a literal value, then log where readers actually diverge from it.
Free download · No account needed
Troubleshooting Section
[Product], an [n]-step tutorial
The log, in four counts
| Divergence reports logged | — |
| Reports concentrated in the busiest two steps | — |
| Diagnosed reports pointing to a different step than reported | — |
| Report rate after the fix shipped | — |
The distinction a troubleshooting table never makes
Not just which step readers report trouble at. Which step actually caused it, because a normal-looking success response two steps earlier can hide the real defect.
Ranked by cause, not by symptom
Every reported step, with the step the investigation actually traced it to, so the fix lands where it is needed.
What shipped
The exact clause or prerequisite added to the cause step, and the report-rate change measured over the next equivalent window.
Diátaxis, the framework behind most tutorial-writing advice, says an author must rely on users to discover flaws through extensive testing and observation, without specifying what that observation should produce. Google's own docs_advisor guide gets further, describing friction logging: writing down everything that trips a reader up. The output stays a qualitative note per session, never a register tied to a specific step number. Every other page for this query adds prerequisites, runnable code and a troubleshooting table, none of it fed by real reader data.
This pack's Failure Mode Log adds the register: which step a reader reported trouble at, and which step the investigation actually traced it to, because those are not always the same step. On the worked example, Corven Metrics, an invented event-tracking SDK, an 11-step tutorial drew 97 divergence reports across 640 reader sessions in its first 90 days, 71 sessions filing at least one. Two steps, 3 and 7, carried 63 of the 97, 64.9 percent.
29 of those reports were filed at Step 7, "nothing shows up on the dashboard," and 24 of the 29, 82.8 percent, traced back to Step 6, which returns a normal-looking success response while silently dropping the event. The fix landed on Step 6, not Step 7, and the following 90 days, at comparable traffic, saw the report rate fall 77.3 percent. Whether the tutorial's terms match your approved vocabulary is a separate pass, the terminology and glossary pack, and whether an existing page still matches the product a year later is the documentation audit.
What's in the pack
Tutorial
Numbered steps toward one task, each with an Expected Result stated as a literal value a reader can check directly against their own output.
Prerequisites Note
Every prerequisite as a command that prints a checkable result, not an assumption, prioritized by what the Failure Mode Log has already flagged.
Step Verification Register
The same steps in sheet form: action, literal expected result, and a self-check, sortable and filterable.
Failure Mode Log
One row per reader report, with the step reported and the step diagnosed kept as two separate fields, never merged into one.
Troubleshooting Section
Organized by where readers notice trouble, stating plainly when the real cause sits at an earlier step instead.
Cause-ranked fixes
Steps ranked by how often they are the diagnosed cause, not by how often they draw a report, so the fix lands where it is needed.
A space rule every prompt reads first
A symptom step and a cause step are not the same row, and the fix belongs on whichever one actually produced the wrong result.
How to use it
- 1
Open it in River, or download it
Open the pack and the agent drafts the tutorial with a literal expected result on every step, or download the blank documents and sheets.
- 2
Send the task and the prerequisites
What the reader will build, who they are, and what they need before starting, stated as testable commands rather than assumptions.
- 3
Send reader reports once it's live
However readers currently report getting stuck: a feedback widget, a support tag, a comment thread. Each gets logged against the step it named.
- 4
Fix the diagnosed cause, not the symptom
Every report gets traced to the step that actually caused it, ranked by concentration, and measured again after the fix ships.
Frequently asked questions
Is this template free?
Yes. Download the whole pack as Word documents and CSV sheets, no signup and no credit card. Edit with AI is a separate, optional path for anyone who wants the agent to draft the tutorial and log real reader reports against it. Nothing happens until you send it a task to write.
We already have a troubleshooting section. What does this add?
Most troubleshooting sections list errors the writer imagined in advance. This one is built from reports readers actually filed, with two fields per report: the step they noticed it at, and the step an investigation traced it to. On the worked example those differed for 24 of 29 reports filed at one step.
How do readers actually file a report?
Whatever mechanism you already have works: a link under each step, a support ticket tagged to the page, a comment thread, or session recordings. The Failure Mode Log only needs the step number and what the reader saw instead of the stated result. A purpose-built widget helps but is not required to start.
What if a reported failure won't reproduce?
It stays logged as undiagnosed rather than forced into an explanation. On the worked example 15 of 97 reports never reproduced, most one-off enough that no pattern emerged. A finding invented to close a row is worse than an honest gap, because it sends the next fix at the wrong step.
Does this replace testing the tutorial ourselves before publishing?
No. Run every step yourself in a clean environment before it ever reaches a reader; that catches what a writer can catch alone. The Failure Mode Log exists for what a solo walkthrough cannot: how a real, unfamiliar reader's environment differs from yours, at a scale no single test run reaches.
Our tutorial calls an API. Should we check the reference first?
If the reference itself leaves fields unanswered, fix that first: a tutorial built on a thin spec inherits every one of its gaps, and that inventory is the OpenAPI gap workup. If your engineer's answers are what's missing rather than the spec, build the question set with the SME interview pack.
What format are the downloaded files?
Three Word documents and two CSV sheets, zipped. The documents open in Word, Pages and Google Docs; the sheets open in Excel, Numbers and Sheets. Add a PDF query string to the download if you want to circulate the tutorial rather than fill it in.
Find out which step is actually losing your readers
Download the blank Tutorial, Prerequisites Note and Failure Mode Log as Word and CSV, or have River draft the tutorial and log your own readers' reports against it.
Edit with AI