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:ANON: Writing a Tutorial From:jbell <jbell -at- PARAGREN -dot- COM> Date:Fri, 6 Nov 1998 14:31:30 -0500
My advice on tutorial writing is:
layer the information
Some features of software products can be very intensive
with many options, controls, and choices. Presenting all
the information on all controls can take quite a while.
For example, for me to explain how to manage advertising
campaigns with our software takes a full day. Two hours
of that time is spent on understanding the many controls
available on the Allocation window.
We have found the best approach is create three levels
of detail. In the first level, we cover the basics of each
function needed to get a campaign done from start to
finish. In less than an hour each student has created a
campaign and generated a simple mailing list for it. This
quick results gives them the confidence that the software
really does work, and once you know your way around,
you can use it quickly.
As we cover the complex topics, we remind the students
we are just "scratching the surface, more details to come".
In level two, we create scenarios of complex issues, then
we use those scenarios to explain the more advanced
controls on some of the windows.
Level three is similar to level two, but drills down into even
more complex features and inter-relations between features.
At the end of level three, all product features have been
covered, and in a context where the student has been presented
with a problem to solve first, then learns about the feature
used to solve that problem.
--- John Bell
jbell -at- paragren -dot- com