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.
On Behalf Of Sonja McShane wrote:
[...]
>
> I've done some preliminary searching for information about creating
> tutorials and what makes a good tutorial, but oddly enough there
doesn't
> seem to be much around. I'd really appreciate it if anyone could pass
on
> any:
>
> - tips about writing tutorials
> - 'gotchas' I should know about
> - links to examples of excellent online, interactive tutorials
> (preferably explaining how to use software)
> - links to how to write tutorials
> - 'pet peeves' about tutorials you've used in the past.
>
> If you could please send the details to me at
sonja -dot- mcshane -at- str -dot- com -dot- au,
> and I'll post a summary in the next few days.
If everybody (who's going to) writes only privately to you, then:
a) the topic doesn't get discussed on the list (you say you haven't
found much useful discussion about it, so maybe a good discussion here
would help end the drought)
b) most people will imagine that somebody better-qualified has already
privately replied, and you'll end up with few or no replies.
Also, I hope the fact that you posted your "real" address only in the
body of the message wasn't an attempt to defeat the spammers. For that
you would have had to disguise it a bit, too. This list is open to the
universe of spammers and their harvest-bots.
To the actual question... here's my suggestion:
Unless your software is one-of-a-kind - in which case, _any_ tutorial is
going to shine - then there must be forums and discussion lists about
either your software or your competitors' products. Go to those lists,
and their archives, and find out what are the most common questions and
complaints. Then answer those in your tutorial.
I've had more than enough of lovely tutorials that don't address most of
what I do with a piece of software, and do address the showiest features
or the ones that marketing wants to highlight. A large portion of your
audience will (if your product is not unique) come from a background of
having used other similar tools, looking to try/switch-to yours. Another
large segment will come from a background of never having used any such
product. Your tutorial should address both groups, AND it should provide
a way for the experienced-with-similar-tools people to bypass the baby
steps. Forcing everybody to play through all the baby steps is like
forcing them to learn how to use a mouse again, before showing them how
to do the advanced stuff they're looking for.
If you have all the time in the world, then make your tutorial modular
and nested... very much like web sites and e-learning. That is, provide
one or three (or five or...) main paths through the tutorial, but in
every segment, include links to launch further, more-in-depth topics or
alternative branches. And, of course, cross-reference like mad.
Include both breadcrumbs and a "reverse-breadcrumbs" feature... a map to
where the current segment is going. On the links to alternate topics
and in-depth segments, provide tool-tip/hover-"text" maps of the topic
sequences that will be invoked by clicking. This is needed because,
unlike a web-page, where you recognize (even as it's loading) that this
is not where you wanted to go, and you just hit the browser [Back]
button, many forms of tutorial viewing make it difficult or
time-consuming to halt the video or the Flash or the whatever gimcrack
and get back to where you were. It can be agonizing to recognize that
you've launched a segment by mistake and know that you'll have to live
through half of it before the app will even recognize that you are
desperately pressing the [Stop this damn thing!] button... Most people
have limited time in their lives.
If possible, include individual-user logging, so the individual user can
check where they've already been... and if there are multiple users,
each can have her/his own record of where they've been, where they
stopped most recently.... hmmm... it's also nice to be able to resume
other threads than the one that you visited most recently. So, at least
a global map of topics and segments - with active startup links at every
node - would be good. Try to make it two-dimensional, rather than just a
long list.
For any advanced topic, start the segment with "pre-requisites" - stuff
that the student should already know before they get in over their
heads... and of course, give them the opportunity to withdraw without
sitting through half of the segment, if they decide that they lack the
background for this segment, or that it's not going to tell them what
they thought/hoped it would. On the other hand, have an easy-and-quick
way for the student to bypass that preliminary "this is what we're going
to teach you" stuff, if they've been here before and just want to "just
get on with it".
Well, I wish I had some good ideas for you, but somebody will.
Cheers,
- Kevin
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
ComponentOne Doc-To-Help gives you everything you need to author and
publish quality Help, Web, and print content. Perfect for technical
authors, developers, and policy writers. Download a FREE trial. http://www.componentone.com/DocToHelp/
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
