Re: warning labels

Subject: Re: warning labels
From: Jim Grey <jwg -at- ACD4 -dot- ACD -dot- COM>
Date: Fri, 4 Mar 1994 09:07:50 -0500

Eric Ray asked about warning labels like Warning, Caution, Important, etc:
On a related note, I haven't yet found a effective way
to relate these to computer documentation. When I was
writing for a heavy equipment manufacturer, it was easy
to use Danger, Warning, etc. correctly. Now that I am
doing computer documentation, it is much more difficult
and I have essentially discarded those standards.
Warning, in its ANSI sense, is rarely if ever
applicable

In what we sell, we have no need to comply with ANSI. Since the only way
a person will be harmed by our product is if they drop the tape on their
foot, the most important thing becomes the system, software, and data.

From our _Documentation_Style_Guide_, which we wrote to cover this kind
of stuff:

Notes - Use notes for information which is not essential to the reader's
understanding of the subject at hand. A note may include incidental
information about the subject, a reference to more detailed discussions
of the current subject or of related subjects, or references to other
[products].

Example:

Note: Appendix B provides security worksheets to help you determine
security priveleges before executing ADD.

Cautions - Use cautions to advise readers to consider the results of an
action and proceed with care. The caution explains that the action being
discussed does something that the user may not want, or may do something
the user does not want.

Example:

Caution: If an account with this name already exists, the system
says "name already exists in password file". If the screen
is committed, the existing account is deleted and replaced
by the new account being added.

Warnings - Use warnings to warn readers to avoid specific actions or
situations that always have undesirable results.

Example:

Warning: Do not lock the root segment of the disk. This segment is
continually accessed during normal system operation. Locking
it will cause system failure.

Hope this helps.

jim grey |beebeebumbleandthestingersmottthehoopleraycharlessingers
jwg -at- acd4 -dot- acd -dot- com |lonniemackandtwangandeddiehere'smyringwe'regoingsteadyta
|GO/M d p+ c++(-) l u+ e- m*@ s+/ n+ h f++ g- w+@ t+ r- y+(*)
|Terre Haute, IN -- The Silicon Cornfield


Previous by Author: Re: Good books
Next by Author: Re: ti(d/t)bit
Previous by Thread: Re: warning labels
Next by Thread: Article about ratio of writers / developers


What this post helpful? Share it with friends and colleagues:


Sponsored Ads