Re: Writing tutorials

[The Tech Writer <techwrtr -at- CRL -dot- COM>]

On Thu, 16 Jul 1998, Geoff Hart (by way of "Eric J. Ray" <ejray -at- raycomm -dot- com>) wrote:

> First and foremost, start with a list of objectives that students
> must be able to accomplish, not a list of topics. In short, don't
> design each module based on something like "an overview of printing";
> instead, start from the premise that users must learn how to (i)
> print the entire document, (ii) print only a single page of the
> document, and (iii) print on different printers on the network.

I agree wholeheartedly with Geoff's advice. I'm currently rewriting a
paper-based tutorial for a programming tool from the ground up. Things to
keep in mind:

* Tell the user *why* they're doing what they're doing. The previous
tutorial had the user following a bunch of steps to reach a goal, but the
user had no idea what each step was doing behind the scenes.

* Give the user chances to do what you've shown them how to do by
themselves, or with minimal reminders, so that they can get a feeling of
accomplishment. Try to separate the first, hand-holding version from the
do-it-yourself part by a little bit so that they're having to recall,
rather than just turning back a few pages (or clicking a Back button a
few times). Give them cross-references to the place where they did it
before so that they can brush up if they've forgotten how.

* Give your existing users a way to skip the introductory stuff. We split
our tutorial into two sections: the basics, and advanced exercises. Then
we give them a model (which is what we call the "source code" for a
program) that is done through the basics, so they can start on the
advanced exercises if they want to.

* Follow the old "Tell 'em what you'll teach 'em, teach 'em, then tell
'em what you taught 'em" process. Vary the level of detail so that
they're not just reading the same text for both. Tell them what they've
learned how to do, especially using the different terminologies by which
other users of the product might refer to the tasks. That way, when a new
person is asked if they have learned how to "Fubar the gizmo," which is
the same thing as "Applying fubar to a whatchamacalit," they'll know what
they know.

-David Castro
 techwrtr -at- crl -dot- com