September General Meeting:
The Terrible Truth About Tutorials

by Darlene Woods, Quill Contributor

During his presentation, "The Terrible Truth About Tutorials," at the September general meeting, Peter Vogel proved that technical writers are just like their users!

Mark Ladoucer attempts to draw a picture (foreground)
being described by someone else. The person describing
the picture could not let participants see the picture
or communicate in any way other than with words.

We don't follow tutorials step by step; instead, we modify them in order to accomplish our own goals in our own timeframe.

Some Truths About Tutorials

Through Peter's informal presentation and some hands-on group exercises that tested our ability to follow instructions, we discovered the following truths:

• Tutorials are examples of how to perform a specific task that the technical writer chooses. Users want to perform tasks that are important to them. Therefore, we need to make sure our tutorials are about what the users consider important and relevant.
• Users want feedback. "Am I doing this right?" "Is this what I'm supposed to see?" We need to provide pictures and expected results, so that users know they're on the right track.
• Users will not always follow step-by-step instructions written like a contract that say, "You must do this, then that." What they want is a cookbook approach that leaves room for flexibility and variance in audience goals.
• Mistakes will happen! People using tutorials are often trying things for the first time. They will make mistakes. Hints, tips, and warnings about potential problems, and explanations of how to correct mistakes, are helpful to include for users. When they get back to their regular work, they will make mistakes. So, giving them warning up front and providing troubleshooting solutions go a long way in helping them apply what they learned in the tutorial.

Parts of a Good Tutorial

There are three parts to a good tutorial:

1. A task-oriented introduction — so that users can find the tutorial that fits their needs. Make each tutorial independent.
2. Steps with feedback — to let users know what to do when things go right and when things go wrong.
3. A summary — to provide context for the user's accomplishments. Sometimes by the time they're done, they have forgotten exactly what they set out to do.

Different Formats for Different Audiences

Peter pointed out that there are two basic formats for tutorials: playscript and minimalist.

As with any writing, just because we are like our users, do not assume that what you have written is what you meant to say. Test, test, test (with real users), then rewrite, rewrite, rewrite!

About Darlene Woods

Darlene is currently a technical writer for Witness Systems, a leading global provider of performance optimization software and services. She has spent the last eight years as a technical writer in the software industry in K-W. Before that, she spent several years as a technical writer and trainer in the financial industry.