Re: ANON: Writing a Tutorial

[Yvonne DeGraw <yvonne -at- SILCOM -dot- COM>]

Anonymous wrote:
>Does anyone have any opinions or suggestions? If anyone knows of or
>has written up a guide or plan for writing a tutorial, I will be very
>grateful to find out.

I'm not sure why you need to be anonymous on this, but my presentation on
"Writing Tutorials that Teach" is available at
http://www.silcom.com/~yvonne/tutor/index.html

>My problem is that no one has given me any direction as to what the
>tutorial should do. My initial impulse is to just to make up my own
>sample project and walk users through creating that project using the
>software.  Of course, I won't be able to walk users through all the
>features, so I'll probably just do those that are most commonly used.

In general--yes, I'd recommend making up a sample project that is relevant
to the real-world projects users will have. The important thing is to know
your audience.

Your instinct to cover the commonly used features is also good. I think
tutorials do best when they move a user from the novice stage to an
intermediate user stage. In the tutorial, give them the tools to later move
beyond the intermediate stage -- that is, get them to use the online
help/reference doc.

During my presentation, we did a case study in which we listed the tasks you
can do with email software like Eudora. The list was pretty long. We crossed
off things that users didn't need to know in order to be intermediate users.
That gave us a task list with a reasonable length.

I prefer to structure tutorials as a series of lessons that show increasing
levels of complexity. Depending on your software, this may build on the same
example or use different examples. Think of the progression as showing the
user how to peel an onion. The first lesson should be relatively short and
give the user a sense that they accomplished a real task with this product.
Subsequent lessons should show more complex features.

Have fun. Feel free to ask more specific questions off-line if you are
uncomfortable posting to the list with your name attached.

Yvonne DeGraw, Technical Services     o Technical Writing
yvonne -at- silcom -dot- com                     o Online Help
http://www.silcom.com/~yvonne         o Web Documentation
Tel: 805/683-5784                     o Database Publishing
Santa Barbara STC: http://stc.org/region8/snb

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=