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.
The question of admonitions really has two parts, and (based on
yesterday's digest) we've been talking about only one. We've been
discussing placement, the other part is content.
The way I learned it, there are four levels of admonitions: Danger,
Warning, Caution, Note.
"Danger" means that failing to follow the procedure as written will
likely result in death.
"Warning" means that failing to follow the procedure as written can
possibly result in serious injury or death.
"Caution" means that failing to follow the procedure as written can
result in damage to the equipment or system. Personally, I include
"crashing the software" as damage (even though nothing is actually
broken, it's something the user might very much want to avoid), so I
insert "Caution" admonitions if getting the next steps wrong will result
in a software conniption.
"Note" is used to provide some additional information that may be of use
or make the user's job easier.
"Danger," "Warning," and "Caution" always come immediately prior to the
part of the procedure where the hazard exists, and always on the same
page as the part of the procedure where the hazard exists.
A "Note" can come either before or after the relevant step, depending on
what makes most sense.
Now about the content. Admonitions should contain either safety
information or information which is helpful but not vital to the
procedure. You should be able to delete every note in a procedure, and
yet still perform every step.
Admonitions never never never contain procedural information in
themselves. In other words:
NOT THIS:
DANGER: Disconnect electrical power before unlocking case and removing
wires, failure to do so may cause electrocution
Step 1 Unlock case
Step 2 Remove wire
INSTEAD THIS
DANGER: Failure to disconnect electrical power may cause
electrocution.
Step 1 Disconnect electrical power
Step 2 Unlock case
Step 3 Remove wire
Rick Lippincott
Technical Writer
AS&E*
American Science & Engineering
829 Middlesex Turnpike
Billerica, MA 01821-3907
978-262-8807 (direct)
978-495-2335 (mobile)
978-262-8702 (fax)
This message is intended only for the addressee and may contain information
that is confidential or privileged. Unauthorized use is strictly prohibited
and may be unlawful. If you are not the intended recipient, or the person
responsible for delivering it to the intended recipient, you should not read,
copy , disclose or otherwise use this message, except for the purposes of
delivery to the addressee. If you have received this e-mail in error please
delete it and advise AS&E immediately.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
