Re: ANON: Writing a Tutorial

[Bruce Boyer <bboyer -at- OBJECTSHARE -dot- COM>]

At 10:15 AM 11/5/98 -0700, Anonymous wrote:
>Message forwarded on request. Please
>reply on list.
>
>****************************
>
>I am writing a tutorial for a software product. I have written other
>manuals and online documentation for the product, but this is the
>first time I'm writing a tutorial.
>
>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.
>
>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.

A lot depends on the product.  For a complex product, don't expect
to hit every feature; the tutorial would bog down and be less useful.
For a fairly simple product this shouldn't be a problem.

Similarly, for the example.  An extended example can be useful, though
you may also want a few.  Again, if the product is complex, like
a programming language, you may not have the necessary skill to come
up with a good representative project, so someone else will have to
do it for you.  That has the opposite risk, that the techie will
come up with something too complex to really show off in a tutorial,
so you'll have to work pretty closely.

Avoid, in the tutorial, simply showing how to recreate the example;
I've seen too many do this.  It's an easy way out, but really doesn't
serve its purpose.  The point of the tutorial is to get to know at
least the basic use of the product.

A good tutorial is hard.  Don't slight it.  Good luck

Bruce
************
Bruce Boyer, Ph.D.
Lead Technical Writer
ObjectShare
email: bboyer -at- objectshare -dot- com
************

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