What is how-to guide writing, and what is it not?
It is writing instructions that somebody else can follow to completion, which is a different task from explaining a process or describing how something works. The distinguishing feature is that the reader intends to act, and will find out within an hour whether the document worked, which makes this the only genre on this site where another person's mistake belongs to the author. It is not a tutorial, which teaches a beginner, and not a reference entry, which is looked up. A how-to guide is for somebody who could already do the task and needs the steps. Blurring those three is what produces a document that is padded for a beginner and incomplete for a competent reader.
What should a how-to guide contain?
Six things, and the order matters. Who the reader is, including what they already know. What they need to have ready before starting. What done will look like, described before the first step rather than after the last. The steps, in the order that reader performs them, each asking only for things already available at that point. What commonly goes wrong, next to the step where it happens. And a statement of when the guide was last checked. What it should not contain is background about the organisation or about why the process matters, because the reader came to do a thing and will leave when the thing is done.
How long should a how-to guide be?
Exactly as long as this reader needs and no longer, which is the honest answer and usually much shorter than expected. A reader who has done the task before needs three steps and a list of the differences. A first-timer needs twelve steps and every term defined. Both readers are real and they are not the same reader, which is usually why one guide cannot serve both. The commonest waste is not padding but irrelevance: steps carried over from a longer version of the process that this particular reader would never take. Cutting those steps makes a guide more likely to be finished, not less.
How many steps should a how-to guide have?
Fewer than the author expects, and the number matters less than whether the reader can hold the sequence in their head while working. As a rough guide, anything past about seven or eight becomes a staged procedure, which is a different document with stage checkpoints and a clear outcome for each. The practical test is that every step should have an outcome the reader can see. If two consecutive steps have the same outcome, they are one step. If a step has no visible outcome, the reader cannot tell whether they have finished it or started it, which is where most guides quietly lose people.
How detailed should a how-to guide be?
Detailed enough that a stranger reaches the outcome without asking a question, and no more detailed than that. Over-specifying is a real failure and not only a stylistic one, because every unnecessary step is a place the reader can go wrong, and a reader who follows a step that turns out to be unnecessary will usually conclude that something is wrong with the guide or with themselves. The specific things worth specifying are the ones where readers reliably get it wrong: where to click, what the finished state looks like, and what to do if the screen is not what the guide says.
How do I write steps that are easy to follow?
One action per step, with the action at the start of the sentence in the second person, so the reader can tell what they are being asked to do before they finish reading it. Describe the screen or the object rather than referring to it by a name the author happens to know. Never require a step to use something introduced later, which is the defect that most often loses a reader halfway through. And check the whole sequence by reading only the step headings, because for somebody working from a guide that list may be all they have.
What should a guide say about mistakes and errors?
The common failures, in priority order, each placed next to the step where it tends to happen rather than gathered at the end, because a reader who has just gone wrong is reading that step and not an appendix. Say what the failure looks like as well as what to do about it, since a reader often does not recognise it without being told. And resist covering everything, because a guide describing every exception is never finished and therefore never usable. The handful that actually happen are worth more than the full list nobody reads.
Should a how-to guide include pictures?
Only when they carry information the words would take a paragraph to convey: where a control sits on a crowded screen, what a finished result looks like, what a particular state means, or how a screen differs on another version. A picture of a clean desktop does not transfer to the phone the reader is holding, and a picture showing something obvious is taking up the reader's time. The test is simple and it is quick. Cover the text and look at the picture. If nothing is lost, it was carrying nothing and should be cut.
How do I know whether a how-to guide works?
By giving it to somebody who has never done the task and watching. Record every point where they stopped, looked something up, guessed, or gave up, because that list is the entire review and nothing else comes close. It is inconvenient and takes about an hour, which is why most guides are never tested and most published guides are drafts. Watch for three specific things. A step that asks the reader to decide something. A term used without being explained. And a screen described from memory. Repeat once after fixing, since the second attempt surfaces a smaller set.
How do I keep a how-to guide up to date?
Put the last-checked date on the guide and treat it as a real commitment, because that single line is what tells a reader whether to trust it. Set a review trigger on the things that change the procedure rather than on a schedule: a software update, a change of interface, a new person taking the role, or a failure somebody reported. And have somebody who was not involved perform the task on the review, because the author cannot see the gaps in their own process any more. Most stale guides are not neglected, they are simply not connected to anything that changes.
Can you write the guide or do I keep it?
We write it and you own it, because the reader note and the decision about what to assume are judgements only you can make about your own readers. What we produce is the reader note, the step list, the failure note, and the guide itself, along with a test record once somebody has attempted it. What we will not do is write steps for a procedure nobody has watched being performed, because that is exactly the failure the genre is prone to, and we cannot run the test ourselves. Where the honest finding is that two audiences need two guides, that is said before drafting rather than after.
Where is Writely available, and how do I start?
Writely is based in Nigeria and works remotely with companies, teams and organisations across Nigeria and the rest of Africa. Use the
Chat with us button to say who the reader is and what they already know, because the reader note is written first and everything else follows from it. Send a recording of somebody doing the task, since that is the material the steps are built from, and tell us what they will have available at the start. Say what done should look like, and name anyone who could attempt the draft afterwards. From that we can usually say within one exchange whether this needs one guide or two.