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:RE: Variations on a task From:"Michael West" <mwest -at- oz -dot- quest -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 13 Apr 2000 11:14:28 +1000
Melanie Fielek wrote:
> >The Help does contain one of my pet peeves -- the phrase "do one of the
> >following:" Yuck.
>
> So, how do y'all deal with documenting several different ways of
> accomplishing the same task?
Hi Melanie,
I've never had a problem with that "do one of the following" approach, as
long as the choices are clearly presented, including the basis for choosing.
But I agree that in your example, it is distracting to get hung up on
different ways of opening the file when in fact the instructions are really
for doing something else.
Using your example, you should make "opening a file" a separate procedure
block, covering all the alternatives, then simply cross reference to it from
all other procedures that require opening the file. Depending on your
audience, this may sound 'excessively helpful' for all but the newest users.
As an alternative, if you cover "opening a file" as part of a separate topic
of "basic procedures", then it is probably safe to assume that your user can
find the "open" procedure without the cross-reference if needed -- so you can
just say "Open the file." Try to structure your guide or Help system so that
you don't have to keep repeating basic procedures (such as how to open a
file) everytime you want to tell them how to do something.
In general, though, on the question of giving multiple ways of doing the same
thing, I'd suggest the following.
1. If it really is exactly the same thing -- for example, using a toolbar
button versus using a keyboard shortcut -- it will simplify things for you
and your user if you stick with the menu method (or the "official" or
"preferred" method) in your instructions, but also include a separate
generic topic that explains the shortcuts for everything.
2. Be sure that the two (or more) ways of doing something are really doing
EXACTLY the same thing. For example, there may be different methods of
accomplishing a task depending on where you start from. I wouldn't
necessarily consider these the "same thing."
This requires a task-based approach: the procedure should be seen as part of
a larger process equating to what it is that the user is really trying to
accomplish.
