"Getting started" manual

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

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

Previous by Author: Technical review guidelines
Next by Author: "Getting started" manual
Previous by Thread: Word97 includefile and Visio problem?
Next by Thread: "Getting started" manual

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads