Writing guide
How to write a how-to guide
The hardest part of writing a how-to guide is that you already know how. Psychologists call it the curse of knowledge: once you know something, you cannot fully remember not knowing it. It is why experts write “simply configure the webhook” — a phrase hiding three undefined terms and a skipped prerequisite in five words. The author performed that step on autopilot; the reader hits it like a wall.
Readers rarely abandon guides because the task is hard. They abandon at the first gap between what the guide says and what their screen shows — an unlisted prerequisite, a renamed button, a step that silently assumed the previous one worked. The fix is mechanical rather than heroic: prerequisites before step one, one action per step, and a checkpoint after every few steps so failure is caught where it happened instead of ten steps later.
This guide covers the structure that gets readers to the finish, a process built around recording yourself doing the task, and a before-and-after rewrite of a typical “simply do the thing” passage.
What it is
A how-to guide walks a specific reader from a starting state to a finished outcome through numbered, verifiable steps. It is task documentation, not topic coverage: success is measured by whether the reader completes the task on the first pass without opening a second tab.
When to use it
Use a how-to guide when readers search “how to do X” intending to do X now — onboarding, support deflection, and task-intent SEO all qualify. Do not use it when the reader needs to understand rather than do (write an explainer), when the right steps depend heavily on the reader’s situation (write a decision guide first), or when the interface changes weekly — screenshots rot, so link to living documentation instead of republishing it.
The structure that works
Outcome promise
Tells the reader what they will have at the end, who this is for, and how long it takes — before asking for any effort.
- Name the finished state in the first sentence: “By the end, you’ll have X running on Y.”
- State time and difficulty honestly — “about 20 minutes” builds more trust than “quick and easy.”
- Declare the assumed skill level: “no code required” or “assumes you can edit DNS records.”
- Show the end result up front — a screenshot of the finished state is the strongest motivation to start.
Prerequisites
Lists everything the reader needs before step one, because discovering a missing requirement mid-task is where guides get abandoned.
- List accounts, permissions, tools, versions, and any costs — all of them.
- Anything that takes more than 5 minutes to obtain gets its own link or mini-guide.
- State what the guide was tested on: “tested on WordPress 6.7, February 2026.”
Numbered steps with checkpoints
The core of the guide: one action per step, each verifiable, so the reader always knows whether they are still on the path.
- Start every step with an imperative verb: Click, Paste, Select, Run.
- One action per number — an “and” in a step title usually means it should be two steps.
- Add a checkpoint every 2-3 steps: “You should now see a green Connected banner.”
- Screenshot every point where the screen determines the next click; name UI elements exactly as labeled.
Troubleshooting
Catches the 3-5 real ways the task goes wrong, so a reader who hits one recovers instead of leaving.
- Source failures from support tickets, comments, and a test run on a clean account — not from imagination.
- Format each as symptom → cause → fix.
- Quote error messages verbatim so readers can find them with Ctrl+F and search engines can match them.
FAQ
Answers the questions of people who have not started yet or have just finished — scope, variations, and undoing.
- Cover the variations you deliberately excluded: “Does this work on Mac?”
- Answer maintenance questions: how to undo it, when to redo it.
- Keep each answer to 2-3 sentences; long answers belong in the body.
Step by step
- 01
Define the finish line and the starting line
Complete this sentence before writing anything: “This guide takes a reader who has X to a working Y in Z minutes.” If you cannot fill in all three blanks, the scope is fuzzy and the guide will sprawl.
One outcome per guide. “Install and customize the theme” is two guides wearing one headline — the reader who only needs the install must wade through customization, and the search engine cannot tell what the page answers. Split it.
- 02
Do the task yourself and record every action
Screen-record a full run of the task, including the waits, the logins, and the dialog boxes you dismiss without thinking. The recording is your defense against the curse of knowledge: memory says the task has 6 steps; the recording shows 14.
Note your hesitations. Every place you paused to find a button or decide between options is a place the reader will stall for ten times longer — those moments need a screenshot or an extra sentence, not a “simply.”
- 03
Write the steps from the recording, one action each
Walk the recording and give every discrete action its own numbered step, opening with an imperative verb: Click, Paste, Select, Run. Name interface elements exactly as they appear on screen — “click Save & Publish,” not “save your changes.”
Where you compressed on autopilot, decompress. “Log in and open settings” is three steps for someone who has never seen the product: sign in, find the avatar menu, choose Settings. When in doubt, split; readers merge trivially but cannot un-merge.
- 04
Add a checkpoint after every 2-3 steps
A checkpoint states what the reader should observe if things are working: “You should now see a green Connected banner.” Checkpoints let readers fail fast and locally — without them, a mistake at step 4 surfaces as a mystery at step 12, and the reader blames the guide.
Write checkpoints as observations, not reassurances. “The domain is now connected” asserts; “dnschecker.org should show your new host within 15 minutes” lets the reader verify. Include realistic wait times wherever the system is slower than the reader’s patience.
- 05
Front-load the prerequisites
Harvest every account, permission, tool, version, and cost from your recording and list them above step one. The test: a reader who satisfies the list should be able to finish without opening a new tab you did not give them.
Date-stamp the environment: “tested on WordPress 6.7, February 2026.” It tells readers whose screens differ whether the guide or their version is the problem, and it tells you when the guide is due for re-verification.
- 06
Write troubleshooting from real failures
Run the task again on a clean account or second machine and collect what actually breaks — expired tokens, missing permissions, propagation delays. Add the 3-5 most likely failures as symptom → cause → fix entries.
Paste error messages verbatim, in code formatting. Readers search their exact error text; a troubleshooting entry titled with the real message is findable, one titled “common issues” is not.
- 07
Test on a person who has never done it, then cut the preamble
Hand the draft to someone unfamiliar with the task and watch them work without helping. Every place they stall marks a missing step, a mislabeled button, or an absent screenshot. One observed test finds more gaps than five rereads.
Finally, cut the introduction to under 100 words. Task searchers arrive mid-intent and scroll straight to step one; every paragraph of history and throat-clearing above it is friction. Move context you cannot delete into the FAQ.
Before and after: what good looks like
Before
Setting up a custom domain is easy. First, make sure your DNS is configured correctly. Simply add the required records at your registrar and wait for propagation. Once that’s done, verify the domain in your dashboard and enable HTTPS. If you run into issues, double-check your settings or contact support. That’s all there is to it — your custom domain should now be working.
After
Step 3: Add the DNS records at your registrar. Log in to your registrar (Namecheap, GoDaddy, or Cloudflare), open DNS settings for your domain, and add two records: a CNAME with host “www” pointing to “sites.example-app.com”, and an A record with host “@” pointing to 203.0.113.40. Save both. Checkpoint: enter your domain at dnschecker.org — within 15-30 minutes it should show sites.example-app.com, though propagation can take up to 48 hours. If it still shows your old host after an hour, see Troubleshooting: “CNAME not propagating.” Step 4: Back in your dashboard, open Settings, then Domains, and click Verify.
The before compresses six actions into “simply add the required records” and offers no way to know whether any of them worked. The after names the registrars, specifies both records with exact hosts and values, and inserts a checkpoint with a concrete success signal and honest wait times — so the reader verifies progress at step 3 instead of discovering a dead domain at the end. Note the failure path routes to a named troubleshooting entry, not “contact support.”
Mistakes that sink a how-to guide
| Mistake | The fix |
|---|---|
| “Simply,” “just,” and “easy” hiding real work | Delete the adverb. If the step is genuinely simple it needs no label; if it is not, the label insults the reader stuck on it. Expand the step instead. |
| Multiple actions packed into one step | Split at every “and then.” One imperative verb per number; readers can merge steps themselves but cannot un-merge yours. |
| Prerequisites revealed in the middle of the task | Harvest every requirement from a recorded run and list them all above step one, with links for anything that takes over 5 minutes to get. |
| No checkpoints anywhere | Add a “you should now see…” observation every 2-3 steps so errors surface where they happen, not ten steps downstream. |
| Screenshots that no longer match the interface | Date-stamp the guide, re-verify every 6 months or after any UI change, and re-shoot only the screens that changed. |
| A 400-word introduction before step one | Cap the preamble at 100 words. State the outcome, time, and prerequisites, then start. Background moves to the FAQ. |
Pre-publish checklist
- The first sentence states the finished outcome and the time required.
- Every prerequisite, with versions and costs, appears before step one.
- Every step begins with an imperative verb.
- No step contains more than one action.
- A checkpoint appears at least every three steps.
- Every decision point has a screenshot or the exact UI label.
- “Simply,” “just,” and “easy” appear nowhere in the guide.
- Troubleshooting covers at least three real failure modes with verbatim error text.
- Someone who had never done the task completed it using only the guide.
- The tested version and date are stated.
- The introduction is under 100 words.
Free tools for this work
Check your how-to guide before it ships.
Frequently asked questions
- How many steps should a how-to guide have?
- 5 to 12. Below 5 the task probably does not need a numbered guide; above 12, group the steps into named stages so the reader can see progress and resume after interruptions.
- How long should a how-to guide be?
- 1,500 to 2,500 words covers most tasks that deserve a standalone guide and matches what wins task-intent searches. Completeness sets the floor, not word count — cut the intro before you ever cut a step.
- How many screenshots does a how-to guide need?
- One at every point where the screen determines the next action — in practice every 2 to 3 steps. A text-only guide works only when every step is a command the reader can copy and paste.
- How often should I update a how-to guide?
- Re-verify every 6 months, or within a week of any UI or version change, and display a “last tested” date. A guide that references a renamed button loses the reader’s trust at exactly the moment they needed it.
Free download
The Pre-Publish Checklist
This guide covers one format. The checklist covers every article. 47 checks WriteZu runs before an article ships — as a checklist you can run by hand.
No spam. The checklist, then only what's worth knowing.
Or let WriteZu handle the writing for you
It follows this exact structure — researched, drafted, scored against quality gates, and published to your CMS — while you approve from your inbox.
Start free