Using scenarios in documentation?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Patricia Robertson plans <<...to use a full-fledged scenario to explain at a
high level how users might use all the different modules of our product,
which is enterprise sourcing software. Then I plan to use bits of scenarios
to go more in depth to illustrate the concepts of the various software
modules.>>

Good idea. One thing I find lacking from most documention is a clear
overview of what the product does--not a features list with inflated
marketing claims, but rather how the product could integrate with my daily
workflow and help make my life better. For the page-layout scenario for a
desktop publishing program, the high-level scenario might discuss designing
a page, designing type, importing text, and printing the page or preparing
it for a printer. The lower-level scenario for the "designing a page" topic
might be a quick primer on the tasks you need to do in this context: pick a
page size, choose a grid, define columns within that grid, add recurring
elements such as running footers, and so on.

This kind of information isn't necessary for people who already know how to
use the software, but for newcomers and for otherwise intelligent people who
simply aren't comfortable with computers (and we all know many of these
people), this kind of information is immensely reassuring and helpful: it
tells them we're focusing on their needs, not simply on descriptions of the
software. For people who are experienced with computers and the particular
type of work the software is intended to help them, you still need to tell
them how their knowledge of the work will help them work with the software.
(You'll often hear the term "metaphor" used to describe the way software
relates to the real world.)

<<Has anyone had experience dealing with scenarios in their doc?>>

I do it all the time in my online help. Because we haven't got enough
resources to routinely develop wizards, I always include a section "these
are the tasks you will probably want to accomplish with the software", and
for each task, I provide a high-level overview of the steps required to
complete the task. Each step contains a link to the "reference" material in
the help that describes in painful detail <g> how to do that step.

Where there's a clear sequence for how to accomplish a particular task, I
spell out that sequence in an efficient order. Sure, there may be other
orders, but at least I've shown the reader one good way to do it so they
won't have to invent an approach on their own. And I do emphasize that this
is just one way to work, and that there are others. (By the way, if there's
an approach that I know is ineffective, risky, or otherwise problematic, I
also point that out. Why make the reader repeat the mistakes I made when
learning the software?) This sequence also links to the appropriate
reference material. Plus, there's always a note at the start of the sequence
reminding readers that after they've performed a step (following the
instructions they see after following a link), they should click the Back
button to return to the sequence so they can continue with the next step.

<<There are issues like what voice to use, third I think is best>>

I'm not fond of third person, because it routinely leads to passive voice
and results in descriptions that make it hard to discern who the actor is.
Second-person and imperative work far better. I'm writing this to tell _you_
what to do, and whom to consult for those steps you can't do yourself. I'm
not writing about some hypothetical person and making you infer how that
person relates to your situation.

<<whether to use a single scenario or several different ones, depending on
the module>>

"Depending on the module" is the key. Different modules will require
slightly different approaches, depending on their complexity. The key is to
avoid getting hung up on the definition of "scenario". Don't worry about
what to call it; just figure out what the reader is trying to do, and break
that process down into logical, bite-sized chunks.

<<how much detail to give>>

In principle, you should separate the detailed steps from the broad
overview; the overview should be detailed enough to list all the steps, but
not so detailed that readers lose sight of the overall flow of the task. See
my desktop publishing example (above) for one way to look at this.

<<whether to give a bit of the scenario and then explain the concepts
involved in that bit>>

Definitely. Provide the information that people need to know so they can
understand the overall process, and teach them any terms they need to know
before they can work with the software. Once they understand where they're
starting from, where they're going, and the mile markers along the way, then
they have a good mental model (schema) of what they must do. You can then
develop the specific details of the procedures that fall within that schema.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"The skill of writing is to create a context in which other people can
think."--Edwin Schlossberg, designer (1945- )

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Buy ComponentOne Doc-To-Help 6.0, the most powerful SINGLE SOURCE HELP
AUTHORINGTOOL for MS Word. SAVE $100 on the full version and $50 on upgrades.
Offer ends Oct 31, 02 (code: DTH102250). http://www.componentone.com/d2hlist1002

All-new RoboHelp X3 is now shipping! Get single sourcing, print-quality
documentation, conditional text and much more, in the most monumental
release ever. Save $100! Order online at http://www.ehelp.com/techwr-l

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.