How to [do the task]
One task, for a reader who already knows what they want to do. Title it “How to” plus a verb and an object, in the reader's words. Replace the blue placeholders and delete the grey notes as you go.
Applies to | [Product, version or plan] |
Time needed | [About N minutes] |
Last tested | [Date, by whom] |
Introduction
One or two sentences: when the reader would do this, and what they will have at the end. Answer the worry that makes people hesitate.
[Use this when … . When you finish, …]
See an example introduction
Replace the audio when you need to fix a published episode, for example to cut a mistake or improve the sound. The episode keeps its title, its page and its download count.
From Castwell, an invented podcast host.
Before you begin
Only what the reader must have or check before step 1. Delete this section if the answer is nothing.
Permissions: [role or access the reader needs]
You need: [file, version, device or setting]
Note first: [anything to write down now and check at the end]
Steps
Introduce the steps with a full sentence. In each step: where, then the action, then what the reader sees. Put conditions first and mark optional steps “Optional:”.
[To do the task, follow these steps:]
[In the place where it happens, do the first action] You should see: [what changes]
[Second action] You should see: [what changes]
[If a condition applies], [do this]. Readers it doesn't apply to skip the step.
Optional: [an action some readers want]
[Last action] You should see: [the screen or state that shows the task is done]
See example steps
In Episodes, select the episode.
Select Edit, then the Audio tab.
Select Replace audio. A file browser opens.
Choose the new file. A bar shows the upload's progress.
If the episode has chapter markers, select Review chapters, then drag any marker that no longer lines up with its section.
Select Save. The status changes to Processing, then to Published, usually within two minutes.
No teaching in the steps. If a step needs a paragraph of why, move it to a concept page and link it. If the branches outgrow the steps, write two guides.
Result
[What is true when the task is done, and how the reader can check it]
If it doesn't work
Start each row from what the reader sees, quoted exactly as it appears on screen.
What you see | Why | What to do |
[Exact message or symptom] | [Cause] | [Fix, or who to contact and what to send them] |
[Exact message or symptom] | [Cause] | [Fix, or who to contact and what to send them] |
Related tasks
[How to … (the task readers usually do next)]
[How … works (the concept page behind this task)]
Before you publish
The title is “How to” plus a verb and an object
Everything the reader needs is listed before step 1
Each step says where, then what, then what the reader sees
Every condition comes at the start of its step
The result says how to tell the task worked
Someone who knows the product but not this task followed it without help
The Last tested date is filled in