How to document multiple paths to the same goal?

Subject: How to document multiple paths to the same goal?
From: "Geoff Hart" <Geoff-h -at- mtl -dot- feric -dot- ca>
To: TECHWR-L -at- lists -dot- raycomm -dot- com
Date: Thu, 16 Sep 1999 11:46:43 -0400

Amy Lattof wondered <<What do you do when the software
you are documenting has two paths for most of its tasks? For
example, to launch an application you might: a. Select Tools
> Run > MyApp, from the menu bar. or b. Click the MyApp
button on the toolbar.>>

There seems to be a trend in much of the documentation I've
seen to document only the menu command, and (as you
suggested) provide a list of shortcuts elsewhere to keep the
text relatively uncluttered. I like and accept the reasoning
behind this: unless you're specifically trying to teach all users
all the possible ways to get a task done, you just confuse
people by giving them too many choices. (This is NOT a
comment on the alleged stupidity of users, but rather an
observation of basic human behavior that I've seen repeatedly
in my years of doing this work. Some people really do want
to know all their options, but they're in the minority.)

<<my manager wants to document both paths in the main
procedure. Sooo, it would go some thing like: Select Tools >
Run > MyApp from the menu bar, or click the MyApp button
on the toolbar.>>

How about a compromise? Since the buttons don't really
require any explanation that isn't already present in the
accompanying text that describes the menu procedure, put the
button for each step in the left margin, beside the text that
describes the procedure. Then make it clear in the "how to
use this manual" or "getting started" section what you're
doing and why. For example (and feel free to revise this):
"We've put the menu commands for all tasks right in the text
to help you learn how to get around the program's menus. For
those who prefer button shortcuts to menu choices, we've
displayed the buttons that accomplish the same task in the
margins beside the text. Pick whichever approach best suits
your working style. We've included a complete list of
shortcuts and alternatives in Chapter X..."

--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca (Pointe-Claire, Quebec)
"Perhaps there is something deep and profound behind all those sevens, something just calling out for us to discover it. But I
suspect
that it is only a pernicious, Pythagorean coincidence." George Miller, "The Magical Number Seven" (1956)




Previous by Author: Books on book production?
Next by Author: OT: Need advice from anyone who's worked with Director
Previous by Thread: RE: Technical Writing Courses - training company
Next by Thread: thoughts on international tech writing?


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

Sponsored Ads


Sponsored Ads