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