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.
I just released a six-page instruction on how to
upgrade one of our products from 1.x to 2.0.
I, or somebody that I was watching, went through
the entire procedure, step-by-step via a Windows
admin client and also via a couple of different
UNIX systems.
A few days later, we got complaints from a
customer -- most of which would have been
answered either by reading the instructions
more closely, or by paying attention to onscreen
progress messages (it's all text-terminal, not GUI).
However, one complaint made me take notice:
Our units use token devices for backup storage.
The tokens need to be initialized, by a process
that is as secure as the process to initialize
the system unit and set to up its authentication.
That is, you can't do anything with a backup token
until you authenticate to it... and you can't
authenticate until you have initialized the token
to match with the system it is intended to backup.
So, the customer complained that the upgrade instructions
had exhorted him to upgrade all backup tokens when
the system was being upgraded, but did not tell him
that he had to initialize those tokens in order to
be able to access them to run the upgrade on 'em.
He had practiced an upgrade with his "lab" system
and backup token, but had then embarrassed himself
when he found himself floundering during a real-life
production upgrade.
Hmm. The user manual is pretty clear that you must
initialize before you can do the usual work (i.e.,
backups and restores). But this was a separate,
stand-alone upgrade procedure doc. Hmm.
The customers of which I had previously been aware
would always receive new tokens and initialize them
right away, so that they would know that each one
was perfectly functional and ready when needed...
even if they were then to go onto a shelf as spares.
This guy, though, left the tokens on the shelf
untouched, because HIS procedure (and that of his
security auditors) demanded that the tokens be
"fresh" and just coming out of their security-sealed,
tamper-evident packages at the time of the system
commissioning ceremony.
So, the question that I have is:
How many of you would likely have caught the omission
that embarrassed our customer?
Is this one of those "you live and learn" situations,
or is it "a competent and thorough TW would have
covered all the scenarios that a customer would
encounter"?? I confess that his situation never even
crossed my mind.
Hmmm.
/kevin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Help Authoring Seminar 2003, coming soon to a city near you! Attend this
educational and affordable one-day seminar covering existing and emerging
trends in Help authoring technology. See http://www.ehelp.com/techwr-l2.
A new book on Single Sourcing has been released by William Andrew
Publishing: _Single Sourcing: Building Modular Documentation_
is now available at: http://www.williamandrew.com/titles/1491.html.
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
