warnings, cautions, notes in sw documentation

[David Spreadbury]

The use of Warnings, Cautions, and Notes, specifically Warnings and Cautions, are used differently in different technologies.

Here are some links that may hep you to decide which use best fits your needs:

http://www.techcommunicators.com/dkmanual/chap5015.html
http://www.techcommunicators.com/emanuals/wrm/chap06/06-13_notes.htm
http://www.stc-soc.org/quill/2004-05/warnings.html
http://www.tpub.com/content/tentsshelters/TB-9-2320-360-13-P-2/TB-9-2320-360-13-P-20234.htm
http://www.techwr-l.com/archives/0403/techwhirl-0403-00541.html
http://goodtools.net/pages/SUNstyle/constr8.htm
http://support.dell.com/support/edocs/systems/op990/en/SM/SFF/GUID-EA258A9C-D5EA-43BE-9A44-E8B52A0E594F.html

And MIL-STD-38784C states:
WARNINGS : Highlights an essential operating or maintenance procedure, practice, condition, statement, etc, which, if not strictly observed, could result in injury to, or death of, personnel or long term health hazards.

CAUTIONS: Highlights an essential operating or maintenance procedure, practice, condition, statement, etc, which, if not strictly observed, could result in damage to, or destruction of, equipment or loss of mission effectiveness.

NOTE: Highlights an essential operating or maintenance procedure, condition, or statement.

Another thing that most people don't adhere to is that WARNINGS should come before CAUTIONS, which should come before NOTES, when any two, or all three, may apply to the following paragraph or section.

--- On Mon, 8/1/11, mathieu jacquet <bobitch at hotmail.com> wrote:

From: mathieu jacquet <bobitch at hotmail.com>
Subject: RE: warnings, cautions, notes in sw documentation
To: hessiansx4 at yahoo.com, framers at lists.frameusers.com
Date: Monday, August 1, 2011, 5:33 AM






Hi hessiansx4,

Here is how we define them in our doc:

. Warning mention (+ pictogram): WARNING indicates a potentially hazardous situation which, if not avoided, can result in death or serious injury.

. Caution mention (+ picto): CAUTION indicates a potentially hazardous situation which, if not avoided, can result in minor or moderate injury.

. Caution mention (without picto): CAUTION, used without the safety alert symbol, indicates a potentially hazardous situation which, if not avoided, can result in equipment damage.

We talk about "equipment damage" because our soft is used for remote equipment control.

Mathieu.

> Date: Sun, 31 Jul 2011 20:42:37 -0700
> From: hessiansx4 at yahoo.com
> Subject: warnings, cautions, notes in sw documentation
> To: framers at lists.frameusers.com
> 
> Hello all! I've noticed that the legacy docs I'm currently working on use notes and warnings (no cautions) for a software product. I asked why a warning was used instead of a caution and was told: that's the way we do it here. I've only used warnings when bodily harm could result from some action. How are those of y'all in the sw world doing it? 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.frameusers.com/pipermail/framers-frameusers.com/attachments/20110801/793af516/attachment.htm>