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:"Getting started" manual From:"Geoff Hart (by way of \"Eric J. Ray\" <ejray -at- raycomm -dot- com>)" <ght -at- MTL -dot- FERIC -dot- CA> Date:Fri, 11 Sep 1998 09:29:08 -0600
Lisa Depenbrock proposed the following contents for a "getting
started" manual: <<Logging On, Logging Off, Screen Components,
Navigation, How to use the online help, Overview information
of the system components>>
That looks pretty reasonable to me, provided that the "overview
information" comes first and provides a really tightly written
explanation of the 5 w's:
Who is this manual for (e.g,. advanced users, beginners)?
What is this software (what can I do with it, and what can't I do)?
Where (in what situations) will I use it?
Why would I want to use it to do these things?
When will I use it (e.g., what functions do I have to do elsewhere)?
Juggle the order of these questions and answer to match your context.
If there's an overall metaphor, explain that so that readers know how
everything else in the manual fits within that metaphor. Another
thing to include would be a tutorial. I really hate the type of
tutorial that walks you through a series of preprogrammed steps
without ever telling you what I'm doing and why I'm doing it
and how I could do it differently, and I suspect I'm not alone. So
explain what you're hoping to achieve with each exercise, explain
why each step must be done, and allow the student to diverge from
the beaten path and then return. For example, don't require
the person to pick a font size of 14.3 points so that the rest of the
steps will work: tell them to pick _any_ font size, and make sure
that the subsequent steps will still work. (Of course, if there are
limits on font size, make sure you explain these so the student won't
pick inappropriate numbers and screw up the rest of the exercise.)
Consider including the tutorial as separate tasks inserted within the
rest of the documentation rather than as a standalone chapter; for
example, right after you explain logging on (why do I want to log on?
ok, now _how_ do I log on?), include a "ok, now let's see you do it"
tutorial before proceeding with the rest of the information.
--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca
When an idea is wanting, a word can always be found to take its place.--Johann Wolfgang von Goethe
