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.
re: ... how do y'all deal with documenting several different ways of
accomplishing the same task? This simple example shows what I've been doing
so far:
1. Open a file using one of these methods:
o From the File menu, select Open.
o On the toolbar, click the Open button (pic of button).
2-n. Next step(s) follow.
----
1. I've been known to place a bolded "-or-" between the two ...
1a From the File menu, select Open.
-or-
1b On the toolbar, click the Open button (pic of button).
2. Another way I like is ...
From the File menu, select Open (clicking [pic of button] accomplishes the
same thing).
3. Or even more compact ...
Click File/Open or click [pic of button].
4. Or high-tech ...
Open the file and ... ("Open the file" being a hypertext link to a popup
listing the ways to do it)
Given the "file/open" example, I'd like to suggest we consider when writing
this just how much we are "teaching" our particular software versus how much
we are teaching the operating system, i.e. Windows or Mac O/S or ... .
If these instructions occur within a particular company--as opposed to in a
mass-market manual--"prerequisites" or available references might be
assumed. That being, folks know that the operating system often provides
more than one way of doing things. Really, everyone knows every program
there is has "file/open." (generalization recognized as subject to disproof)
Yes, it depends on your users. If you expect them to be computer novices
(who is a computer novice these days?) maybe the long way is best. Is your
program a "beginner" program, i.e. something likely to be the first program
a user purchases or encounters? If your program is for "geeks," give them
the quick and dirty, i.e. "compact" or "high-tech" alternate.
I many times wrestle with the notion the user already knows the operating
system and I should solely concentrate on the software at hand, and offer
that consideration of this is at least as important as choosing a particular
presenation convention.
