Attention-getters: Warning, caution, danger...

[Barry Campbell]

On 8/28/06, Yves Barbion <yves.barbion at gmail.com> wrote:

> Are there any other references that clearly describe the use of "caution",
> "warning" and other attention-getters?

It's been many years since I worked on an IBM document (over 15!) but
back in the day, IBM's in-house style guide used similar
conventions... "caution" is something that can mess your work up,
"warning" is something that can mess you up, "danger" is something
that can kill you, etc.

We use Microsoft as our in-house style guide where I work now, and
while we occasionally use caution statements, we don't have a need for
anything stronger, as nothing that you can do with our products or
services can endanger your health (unless you hurt yourself by banging
your head against your desk after you mess up a lengthy installation.)

I think that explaining the conventions up front in your documentation
and calling out your caution and warning statements in a really
eye-catching way (with a big box around them, with a graphical icon,
offset from the regular text block, some combination of these),
combined with a clear and unambiguous statement of the nature of the
threat, is all that's required.

- bc

-- 
Barry Campbell <barry at campbell-online.com>
http://campbell-online.com