warnings, cautions, notes in sw documentation

[Brian Emrich]

The definition of Danger, Warning, Caution is defined by several 
organizations. I typically follow the ANSI Z535 standard. ANSI 35 and 53 
are referenced by OSHA. However, OSHA hasn't updated their references to 
reflect the fact that ANSI combined these 2 standards into Z535 many years 
ago. 

Mathieu has the Danger and Warning definitions correct. They currently 
discourage the use of Caution for equipment damage although it is still 
acceptable. There's a new version being published next month that I 
suspect will eliminate Caution as an acceptable term for equipment damage. 


David also mentioned a mil spec that defines the terms and I know that ISO 
also has standards possible injury, although they don't reference the 
different levels of injury. With the attempted harmonization between ISO 
and ANSI, this may be additional changes in the forthcoming update. 

So you need to know the standards that your industry (and country) 
reference and apply those standards to your documents. It is also good 
practice (required?) that you state those definitions in your document.

Brian




David Spreadbury <dspreadb at yahoo.com> 
Sent by: framers-bounces at lists.frameusers.com
08/01/2011 08:28 AM

To
hessiansx4 at yahoo.com, framers at lists.frameusers.com, mathieu jacquet 
<bobitch at hotmail.com>
cc

Subject
RE: warnings, cautions, notes in sw documentation







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? 
_______________________________________________


You are currently subscribed to framers as bemrich at phoenixcon.com.

Send list messages to framers at lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/bemrich%40phoenixcon.com


Send administrative questions to listadmin at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.frameusers.com/pipermail/framers-frameusers.com/attachments/20110801/41d0e3a0/attachment.htm>