User guides and manuals

What a user guide is

A user guide is one document that takes a person from having never used the thing to using it competently, front to back, in the order they will really do things. A manual is the same document for a physical product, usually with more on safety, maintenance and what to do when a part fails. Either way it is meant to be followed in sequence, and it is written that way.

It is not a knowledge base, which is searched one question at a time by somebody already up and running; if that is the actual need, a help centre organised around tasks serves it better. It is also not training material. A guide teaches a product. Training teaches a job, and the two fail for different reasons.

When you need one

You need one when the product ships with a folded sheet nobody reads and your support line takes the same setup call every week. You need one when installation or first use is the point where customers give up, which is where most of them do. And you need one when the product is physical, sold to trades or the public, and a manual is simply expected in the box.

You do not need one if people arrive already knowing what the product does and only ever want an answer to one narrow question. That is knowledge base work, and it is cheaper. If you already have a guide and the complaint is that it reads like a specification sheet, a plain-language edit of what exists will get you most of the way for a fraction of the cost.

How it gets written and checked

The method is the thing being bought here, so it is worth stating plainly. A guide written by somebody who knows the product will be clear to somebody who knows the product. That is the whole problem, and no amount of careful writing by that person solves it.

• The recorded walkthrough. Someone who knows the product does the whole thing while I record and interrupt. Not a description at a desk — the actual sequence, including the bit they do without noticing.
• The draft in task order. Numbered steps in the order a person does them, one action per step, with the screen or the part named exactly as it is labelled on the thing itself.
• The observed run. Somebody who has never used the product is given the draft and left to it. I watch, take the time at each step, and answer nothing. Where they stop, re-read, guess or ask is written down.
• The rewrite. The steps that went wrong are the steps that get rewritten. Steps nobody stumbled on are left alone, however much I might prefer different wording.
• The second run. A different person, the rewritten draft, same rules. Two clean runs and it is finished.

What you get

The guide. An editable document and a PDF, with numbered steps, a troubleshooting section built from what actually went wrong in the observed runs, and a marked list of every screenshot or photograph needed, with a note of what each must show.

The quick start. Two pages covering first use only, for the box, the counter or the first email. Most people read this and nothing else, so it is written first and tested hardest.

The observation notes. A short record of where each tester stopped and what they called things when they were confused. This tends to be the most useful document of the three, because it is a list of the product's labels that do not match the words customers use.

A worked example

An illustration. A Manitoba company builds commercial dough mixers for bakeries and ships them with a 34-page manual adapted from a European supplier's original. Installation calls average two a week, and almost all of them are about the same stage of the first clean-down.

Two bakery staff who have never touched the machine are each given the existing manual and watched. Both reach step six, which says to secure the bowl guard, and both stop, because on this model the part is stamped SAFETY SHIELD and no page in the manual uses that phrase. One of them guesses and turns the machine on with the shield loose. The rewritten guide runs to 21 pages, uses the words stamped on the machine, moves the clean-down ahead of the first mix because that is the order bakeries work in, and puts a one-page laminated quick start in the crate. The troubleshooting section opens with the two failures the testers produced, not the two the engineer thought most likely.

How it runs

1. A half-hour call. What the product is, who uses it, and what your support line hears most. No charge.
2. A fixed price in writing. Length, number of observed runs and whether photography is included, all agreed before work starts.
3. The walkthrough. One or two recorded sessions with the person who knows the product best, plus access to a working unit or a live account.
4. The draft. Within ten working days for a guide of twenty to thirty pages.
5. The observed runs. Two testers, arranged by you or by me, an hour each. You are welcome to watch, and owners who do usually stop arguing with the findings.
6. Delivery. The rewritten guide, the quick start and the observation notes, with the image list for your designer or photographer.

Three to four weeks from first call to a finished guide is typical, and the observed runs are the part worth not rushing.

What it costs

User guides are not a published band on the pricing page, so each is quoted as a fixed price in CAD after the half-hour call. What moves it is length, how many separate models or plans the guide has to cover, whether testers are easy to find, and whether images are handled as part of the job. A single product with one configuration is the simplest version.

What happens next

The observation notes usually produce a short list of support articles worth writing, which sit well inside a support centre sorted the way customers think. Where a step is easier shown than described, the same sequence becomes a training video script using the wording already tested. And if your own staff need teaching rather than your customers, that is training material, a different document with a different reader. The guide is complete on its own, and nothing further is assumed.