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: USA Today article demands printed documentation
Subject:Re: USA Today article demands printed documentation From:Sella Rush <sellar -at- APPTECHSYS -dot- COM> Date:Tue, 16 Feb 1999 15:09:19 -0800
A couple of comments--first, I think the author of the article had valid
points in both of the instances he/she referred to. I think the assumption
the author made about the decision being based on cost was broad and not
valid in all (possibly most) cases.
The second instance, the hardware installation, has been discussed at
length. Personally, I think the author might have been saved some hassle if
he'd followed the directions and read the manual first; but there's no
question the manufacturer should have provided printed instructions in this
I found the first situation more intriguing. How many times have you opened
a new program and not known what to do or where to start? The online help
is task-based and gives great instructions in little tidbits, but is useless
when you don't know what task to take up. We've talked about this issue
here before--when and how do you include global information in an online
In a print manual, it is common practice to begin with opening the program,
discussing the interface, and walking them through a few simple tasks.
Basically, instructions organized in a sequential order--like a tutorial.
The sequence is emphasized by the nature of a book, which has a beginning
and an end.
Not so with online help. No beginning, no end. When I do online help, I
usually set up my table of contents so that there is an implied sequence:
creating a database, adding and editing data, building the index, searching
the data. But this doesn't guarantee that the user will figure it out--even
if they do look at the TOC. (Not to negate Geoff Hart's excellent point
that users/readers must accept some of the responsibility for
It doesn't work well to try to instill sequence in online help task topics.
Trust me--it doesn't. Nor is it necessarily the best solution to scrap a
task-based format and replace it with what amounts to a print-type online
manual transferred to online--you inevitably lose some of the strengths of
online help. As we've discussed on this list, it seems to work better to
separate task based information from overview and general information.
One of the best solutions I've come up with is to create a separate group of
topics that provide an overview of the application--that offer a starting
point and a sense of sequence. I usually place this at the beginning of my
online help TOC, with a title like "Getting Started" (the title depends on
my audience, I might call it a tutorial, or maybe "overview" for more
technical audiences). You could also make "getting started" a separate
command under the Help menu (if you're in Windows). Another option is to
make the overview accessible from an initial splash screen--if you do this
and your audience is novice, then you can also introduce them to the online
Sella Rush mailto:sellar -at- apptechsys -dot- com
Applied Technical Systems (ATS)
Developers of the CCM Database