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.
Joy Zigo is <<... developing (in Word) a reference manual for the use of
support staff at a customer service center. The reference manual covers
web-based tools that customers will use on the internet. Customers will call
-- or, more often, email -- the support staff when they need help with the
tools.>>
My first thought is that since they'll be receiving much of the information
requests online, and the information will be updated often enough to require
pages inserted in a manual, an intranet (based on HTML and a good index)
would be much more effective than printed manuals. (But see notes below!)
I've been on techwr-l for something like 6 years now (eek!), and there's
been pretty good evidence during our discussions that people rarely take the
time to update printed manuals. Plus, a well-designed intranet will be
instantly up to date as soon as you post the new information, and will help
your staff find answers faster than trying to page through an overstuffed
and outdated binder. That productivity argument is mighty persuasive to some
managers. (You'd still want to have a few printed copies around for those
occasions when someone phones in while the network is down, or copy the
intranet to each workstation as a backup.)
<<I recommended some ways to make the manual usable, for example:>>
All your suggestions sound reasonable, but it would be best to bounce them
off the support staff to make sure that they really reflect the way these
people would use the manual. For example, printing only on one side of the
page will double the thickness of the manual, and that means it won't fit on
some shelves or in limited space; similarly, restricting each topic to one
page may artificially limit the length, and that can be a problem for topics
that really do require multi-page documentation.
<<But what kind of pagination would give the most flexibility in terms of
letting users pop new pages in as new features are added to the tools, or
new sets of FAQ's are collected?>>
No pagination system will let you insert a new page between two old pages
without somehow renumbering the new page; in all cases, you need to use
something called an "A-page" (e.g., the page sequence might be 7, 8, 8A, 9,
..), and it doesn't much matter whether you're using simple numerals (1, 2,
3) or numbers with chapter prefixes (1-1, 1-2, 1-3). But then what do you do
about the index? By the time you insert half a dozen new pages, you pretty
much have to replace the entire index. (That's based on personal experience
with updating WHMIS documentation.)
<<in real life, will the company that provides the phone and email support
actually print out and 3-hole-punch and distribute such new pages, anyway?>>
Probably not, unless adding the new material is so much more valuable to
them than answering a constantly ringing phone and responding to 200 e-maiil
messages while the boss grumbles about how expensive it is keeping customers
waiting. Plus, when you add replacement pages, people have to recopy their
margin notes onto the new pages, which is sufficiently time-consuming that
many people simply don't bother changing the pages. You mentioned that they
prefer a print manual, but perhaps this is either (a) a management
perspective that doesn't reflect the way the support staff really work or
(b) the result of having worked with incompetently designed online versions
that left them scared to rely on an online version. Again, I'd suggest doing
a little digging to find out what the real situation is, and why they're
unimpressed with an online solution. Even a simple prototyping exercise
("here's how you find the information... fast. If you like it, I'll add the
actual info to this framework").
"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer
