RE: clarity of terminology can save lives

[Richard Lippincott <richard -dot- lippincott -at- ae -dot- ge -dot- com>]

Kevin McLauchlan  wrote:

> Marketing reviewer spies "Danger" in document, and furiously
 > crosses it out, remarking that we are to avoid any hint or
 > suggestion that our glorious product could possibly be
 > anything but benign.

I dunno, seems more likely to me that while this is going on, the reviewer
in the legal department is frantically scribbling "Danger" above every step
in an effort to avoid liability. "Les'see...step three says 'Use a
screwdriver to open the front panel...' Omigosh! I'd better put in a
warning, 'Do not run with the screwdriver, you'll poke your eye out!' And
what if the users swallow the screws? Or they drop the panels on their
feet?"

More seriously, I first learned the usage of "Warning" and other admonitions
while working on military aircraft manuals, and even in commercial practice
have generally fallen back on the spec definition because it seems useful.

Mil-spec manuals don't use "Danger," they use the following three levels of
admonitions (definitions here lifted from the front matter in the pilot's
manual for the A-10A Thunderbolt II aircraft):

WARNING: Operating procedures, techniques, etc., which will result in
personal injury or loss of life if not carefully followed.

CAUTION: Operation procedures, techniques, etc., which will result in damage
to equipment if not carefully followed.

NOTE: An operating procedure, technique, etc., which is considered essential
to emphasize.

The advantage of eliminating "Danger" is that it resolves the question of
"What's the difference between potential hazard and imminent hazard?"
They're just all hazards, that's all.

There was also the consideration that the admonitions should a) appear
before the step in question, so the user doesn't read the admonition -after-
doing the action, and b) the admonition shouldn't contain any operating
instruction themselves. So, in a hypothetical case, it might go like this:

WARNING: Wear eye protection when removing this panel. The panel is spring
loaded and if improperly removed may fly into your face, causing injury.

CAUTION: Remove the screws in the sequence shown. The panel is spring
loaded, and if improperly removed can be damaged by spring pressure.

NOTE: Lefty loosy, righty tighty on the screws.

1. Use a screwdriver and remove the panel by loosening the screws in the
following order: top right corner first, lower left corner second, upper
left corner next, lower right corner last.

--Rick Lippincott
  Lockheed Martin
  Saugus, MA



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at http://www.ehelp.com/techwr-l


---
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.