Tutorials

What a tutorial is

A tutorial teaches somebody who has never done a thing to do it, once, all the way through, in the order the steps really happen. Every term is defined the first time it appears, every step is small enough to be checked before the next one starts, and nothing is assumed about what the reader already knows.

That last clause is the whole difference between this and a how-to guide. A how-to guide answers "how do I do X" for somebody who already works in the domain: it can say "bleed the line" and move on, because the reader knows what a line is and owns the tool. A tutorial is written for the person who does not know the vocabulary, does not own the tool yet, and will abandon the task at the first sentence that assumes something. The two look similar on the page and are built completely differently.

A tutorial is also not documentation. Documentation describes everything a system can do, arranged by feature. A tutorial ignores nearly all of that and walks one person down one path to one result.

When you need one

You need a tutorial when the gap between a beginner and a first success is the thing costing you money. A software business whose trial users never reach the moment the product becomes useful. A supplier whose customers buy the equipment and leave it in the box. A firm whose new clients must learn a portal or a process before anything can start, and whose staff spend hours a week teaching the same first hour.

It also suits any business selling to people entering a trade or a hobby. Beginners look for things in beginner words, and the piece that treats them as capable rather than stupid is the one they remember when they buy.

You do not need one if your readers already do this work for a living. Writing to a beginner for an expert audience is patronising and they leave. Buy the guide format instead, which is shorter and cheaper. And if the reader does not need to do anything at all, only to understand a term or a rule, the right piece is an explainer.

What goes in it

The finished result, shown first. What the reader will have at the end, how long it takes, and what it costs in tools or materials, in CAD, with the month stated. A beginner needs the destination before they will start walking.

A prerequisites list that is honestly complete. Every account, part, tool, permission and file, gathered before step one. The commonest reason a beginner abandons a tutorial is discovering at step seven that they needed something from a supplier.

One action per step, numbered. Not two. Each step ends with what the reader should now be seeing or holding. A step that cannot be checked is a step where people silently go wrong.

Vocabulary defined in place. Terms are explained the moment they first appear, in the sentence, not in a glossary at the bottom that nobody scrolls to.

The recovery paragraphs. At the three or four points where beginners typically go wrong, a short block saying what that looks like and how to get back. This is what separates a tutorial that finishes from one that is merely correct.

What you get

The tutorial. Typically 1,500 to 3,000 words in a shared document you own, as a numbered sequence, with a prerequisites list, recovery paragraphs, and the headline, title tag and meta description in a box at the top.

An image list. Which steps need a screenshot or photograph and exactly what each must show, with the alt text and captions already written. You take the images; the specification is done.

The novice test notes. One page recording what happened when somebody who had never done the task tried to follow the draft, and what changed as a result. That test is part of the job, not an extra.

Two rounds of revision are included, because the round following the novice test is the one that makes the piece work.

A worked example

An illustration, not a client. A Nova Scotia company sells small-batch soap-making kits and keeps hearing from buyers who opened the box, read the enclosed card, and put everything back in the cupboard. The card assumes the reader knows what trace is, what lye safety means and why a thermometer matters. The owner has been answering the same four questions by email, one customer at a time.

The tutorial is "Your first batch of cold-process soap, start to finish," about 2,400 words. It opens with a photograph of the finished bars and a plain statement that the active work takes ninety minutes and the curing takes four weeks. The prerequisites list names every item, including the two things not in the kit. Fourteen numbered steps follow, each ending with what the mixture should look like at that moment. Four recovery paragraphs cover seizing, separation, a false trace and a batch that will not set. A neighbour of the owner, who had never made soap, worked through the draft in her kitchen and stopped at step six, because "bring both to within ten degrees" did not say ten degrees of what. That sentence was rewritten. The card in the box now carries one line pointing at the page.

How it runs

1. A half-hour call. Which task, who the beginner is, and where they currently give up. No charge.
2. A fixed price in writing. Length, images to specify, the novice test and two revision rounds, agreed before anything starts.
3. The walkthrough. A recorded session in which your most experienced person does the task slowly while I ask the questions a beginner would not.
4. The draft. Ten to twelve working days after the walkthrough, with the image list.
5. The novice test. Somebody who has never done the task follows the draft while I watch. Every hesitation is noted and fixed.
6. Handover. Final tutorial, image list with alt text, test notes and metadata, ready to publish or published for you.

What it costs

Tutorials are quoted as a fixed price after the half-hour call. The price turns on how many steps the task has, whether the walkthrough can be done remotely or needs a visit, how many images have to be specified, and whether a beginner has to be found for the test. A set covering one product line is quoted as a set, since the walkthroughs can usually be done in a day. All figures are in CAD and fixed in writing before the first recording. The pricing page sets out the four ways of working here.

What happens next

Three things commonly follow. The sequence is filmed, using a script written for the ear and the clock rather than the page read aloud. The questions the tutorial raised but did not settle become short pieces answering one question each. And where the same teaching keeps happening live, it becomes material your staff can hand over. None of that is assumed. The tutorial stands on its own, and it is yours from the day it is delivered.