Tutorials, or They won't do what I say (but that's alright, neither do I)

I was editing an article for a programming magazine. The author had got to the part of the article where the reader was walked, step by step, through the solution the author was proposing. The author did a great job of describing how to implement the demo described in the article.

Which, of course, was useless to the article's readers.

You know this is true: Just think about how you use tutorials. You wait until you need to do whatever the tutorial describes (i.e. you wait until you have a problem) and then work through the tutorial. You don't, however, follow the steps in the tutorial. Instead, you pervert many (most? all?) of the steps in the tutorial to solve your problem. Guess what? This is what everyone does.

Authors don't seem to believe this, though (even though that's how they use tutorials). Instead, authors seem to believe that readers will take time out of their lives to work through the tutorial--as the author wrote it--to achieve the demo's goals. In other words, author's believe that readers will do something the reader doesn't need to do, do it right now, and readers will do that in order to achieve something that the reader will throw away as soon as its done.

Seem unlikely to me, too.

So how do you support the 'real world of tutorials'? There are four key things you need to do:

1) Never write a tutorial that demonstrates something or proves that you weren't lying somewhere else in your document. Only bother to write a tutorial if, when the reader is done, readers will have accomplished something they will actually want to keep. And give your tutorial a title that reflects what the tutorial will deliver, not what tool the demo uses. A great title is "Formatting Two-Level Bulleted Lists"; a bad title is "How to use the Formatting Menu"

2) Make every tutorial standalone: The reader isn't going to be working through a series of tutorials; the reader will be going directly to the tutorial that gives them what they want. In the prologue at the start of the tutorial (the part between the title and step 1) tell the reader what they need before they can do step 1. A goal-oriented title and a prologue that describes the prerequisites work together to tell the reader whether your tutorial will get them from where they are to where they want to be.

3) Explain how the step works--"the how" of the step. Readers need enough information about the step to make intelligent decisions about how to modify the step in order to achieve the reader's goals. Omit explaining "the how" of the step only if it is so painfully obvious to your audience that it would be insulting to explain it (e.g. most audiences, when working through an application's Wizard, won't need to be told why they must "Click the Next Button"). Don't, for instance, write "Select the Invoices Table"; Do write "Select the table with the information you want to include in your report (e.g. the Invoices table)".

4) Provide feedback for virtually every step. Because readers will be modifying your steps there is always the chance that your reader will veer off on some dead-end path that will lead to disaster. Let the reader know what they should see/get if they've done everything right.

Don't think that you can omit providing feedback because you've written the step so well that readers can't misunderstand it. Misunderstanding is only half of what can go wrong: readers mistype, misread, mis-select--they make mistakes. Feedback not only tells readers they understood your step correctly, it also tells the reader that they did it right. As with discussing the point of a step, only omit feedback if the result of the step is painfully obvious to your your readers (e.g. most readers won't need to be told that, if they select an item in a list on a computer screen, that their selected item will be highlighted).

None of this new, of course. It's all discussed in John Carroll's book "The Nurnberg Funnel." It's a great book--you should read it.

I have a half-day course on writing effective tutorials that I do for my clients. At the end of one of these sessions, a participant said that she had realized that "tutorials aren't instructional tools--they're enabling tools." Exactly right. I wish that I'd said that.

Let's pretend that I did. Thanks.

Reading or read

• Salem's Lot by Stephen King
• View with a Grain of Sand: Selected Poems by Wislawa Szymborska
• How Do I Love Thee? by Elizabeth Barrett Browning
• To be Continued: American Sound Serials 1929-1956 by Ken Weiss
• The Shadow of the Wind by Carlos Ruiz Zafón