How to write a guide
A guide teaches someone to do a thing. The mark of a great one: a reader follows it and succeeds.
One test decides a guide: someone follows it and succeeds. Not whether it is comprehensive or well written, whether it works in another pair of hands.
Five parts, each preventing one way guides fail: naming the reader, scoping backwards from the outcome, ordering the steps, putting guidance where people stall, and ending with a check they can run.
The parts of a guide that works
Almost every guide that succeeds has the same five parts, and almost every one that confuses people is missing one of them. Use this as your blueprint:
| Part | What it does | The win it delivers |
|---|---|---|
| Audience & start point | Says who it’s for and what they need first | The right reader starts confident and prepared |
| Ordered steps | One action each, in strict sequence | The reader moves forward smoothly, start to finish |
| Concrete detail | Exact commands, settings, results | The reader matches their screen to the page with ease |
| Inline guidance | “If you see X, it means Y” beside the step | The reader keeps moving through the tricky moments |
| A final check | How they confirm success | The reader finishes certain they got it right |
Name the reader, and where they start
A guide written for everyone serves no one well, because the beginner drowns in assumed knowledge while the expert wades through basics. The fix is to decide, explicitly, who this guide is for: what they already know, what they have set up, and what they’re trying to achieve. State it in the first lines. The right reader recognizes themselves instantly and reads on with confidence; anyone in the wrong place finds out before investing their time.
“This guide covers deploying applications.”
“This guide is for developers who already have a working app and a server, and want to deploy it for the first time.”
Scope by working backwards from the outcome
Start at the finish line: what, exactly, will the reader have accomplished? Then list the steps that get there, in order, leaving nothing assumed and nothing skipped. The most common failure in guides is a missing step, the small thing the author does automatically and forgets to mention, because it’s invisible to them and a roadblock to a beginner. Working backwards from the outcome surfaces those gaps before the reader hits them.
One action per step, in strict order
Each step should be a single, checkable action. “Configure and deploy the server” is two steps wearing one number; if a step contains an “and,” consider splitting it. Numbering matters more than it seems: it lets the reader track exactly where they are, and it lets them tell you “I’m stuck on step 4” instead of “it didn’t work.”
What makes steps easy to follow
- Show the exact command, setting, or value, so there’s nothing to guess
- Show what success looks like at that step, so the reader can confirm as they go
- Place guidance right beside the step it helps with
- Group related actions so the path feels natural and the count stays sensible
Show, don’t just tell
Wherever a reader has to match what’s on their screen to what’s on the page, be concrete. “Enable the option” leaves them hunting; naming the exact option and showing what it looks like when it’s on removes all doubt. Concrete detail, the real command, the actual setting, the result they should see, is what lets someone follow along without stopping to interpret. It’s the difference between a guide that reads well and one that works.
Anticipate where readers pause
Every guide has a step or two where people commonly pause, the moment something looks different from the screenshot, or a value depends on their setup. You already know these spots from questions and comments. Name them, right where they happen: a short “if you see X, it means Y” placed beside the step keeps a reader moving exactly when they’d otherwise reach for help. Inline guidance is what turns a guide that works in ideal conditions into one that works in real ones.
For the reusable skeleton behind every step-by-step piece, including where prerequisites and verification belong, see how to structure a how-to.
End with a way to confirm success
Close the guide with a verification: how the reader checks, on their own, that they got there. “You should now see X” or “run this to confirm.” Without it, a reader who followed every step is still left wondering whether they did it right. With it, they finish certain, and that certainty is the feeling a great guide leaves behind.
Quick checklist
- The reader is named, and everything they need is listed before step 1
- Scoped backwards from the finished state, so nothing is assumed
- One action per step, with nothing depending on a later step
- The exact command or setting, and what success looks like at that point
- Guidance beside the step that needs it, not collected at the end
- A final check the reader runs without asking you
Common questions
What’s the difference between a guide and a how-to?
A how-to is one procedure; a guide can hold several plus the context around them. The structure is the same either way, see how to structure a how-to.
How do I keep a guide accurate over time?
Record the versions it was written against and re-run it when they change. Of 1,249 categorised corrections accepted on CitePep, 123 were a figure that had been right once and was quoted forward until the date came off it, which is the same failure in prose. See how to credit contributors.
How detailed should the steps be?
Detailed enough that a reader in your target audience never has to guess or interpret. Show the exact command or setting, and what success looks like at each step. The right level of detail is “could someone in my audience follow this without stopping?”
Where do prerequisites belong?
At the very top, before step 1. A reader who reaches step 4 and learns they needed something from the start loses momentum. Listing accounts, tools, access, and versions up front lets them start fully prepared.
How do I test a guide before publishing?
Follow your own steps with fresh eyes, doing exactly what they say and using only what’s on the page, no filling in from memory. Any gap, missing prerequisite, or out-of-order step shows up fast. Even better, have someone in the target audience try it.