TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: ANON: Writing a Tutorial From:Bruce Boyer <bboyer -at- OBJECTSHARE -dot- COM> Date:Thu, 5 Nov 1998 09:33:29 -0800
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 Boyer, Ph.D.
Lead Technical Writer
email: bboyer -at- objectshare -dot- com