Documentation question: caution vs. warning vs. important

classic Classic list List threaded Threaded
4 messages Options
Ted
Reply | Threaded
Open this post in threaded view
|

Documentation question: caution vs. warning vs. important

Ted
I like the 3 levels of Admonitions used in AsciiDoc. In documentation I equate the levels to safety

1. Caution: Indicates a hazardous situation which, if not avoided, could result in minor or moderate injury.

2. Warning: Indicates a hazardous situation which, if not avoided, could result in death or serious injury.

3. Danger: Indicates a hazardous situation which, if not avoided, will result in death or serious injury.

From the OSHA and ANSI definitions

So when writing documentation I use.

1. CAUTION: (yellow) could result in minor issue.

2. WARNING: (orange) could result in major issue.

3. IMPORTANT (red / danger) will result in major issue.

I don't like the fire icon and generally replace it with the  exclamation-triangle (same as WARNING, but yellow)
e.g. colors and icons

Are there any standards about how these words, colors, or icons are used in documentation? If not, perhaps Asciidoctor should be a leader and set a guide line for their usage?

- Ted @TedAtCIS
Reply | Threaded
Open this post in threaded view
|

Re: Documentation question: caution vs. warning vs. important

rockyallen
From ASD-STE-100 Simplified Technical English issue 7:

NOTE =  "Supplementary information, not essential to the instruction." (Blue circle, white i)
CAUTION = "Risk of damage to equipment." (Yellow triangle, black exclamation)
WARNING = "Risk of death or injury." (Red triangle, black exclamation)

This standard is universal for aircraft, and very common in the defense industry.
The icons are not defined in the standard, they are just what we use.

In our documents we map these to the Asciidoc NOTE,  CAUTION and WARNING and never use the other 2.
Reply | Threaded
Open this post in threaded view
|

Re: Documentation question: caution vs. warning vs. important

rockyallen
Interesting that your ANSI links are completely different to the UK/Europe colours in BS ISO 3864-1:

RED on WHITE = Prohibition (do not smoke)
BLUE = mandatory instruction (wear ear defenders)
YELLOW = hazard (hot, cold, sharp, laser)
GREEN = Safety equipment (escape doors, first aid)
RED = Fire fighting equipment

So all of your ANSI signs would be variations of yellow triangle in the UK?
Ted
Reply | Threaded
Open this post in threaded view
|

Re: Documentation question: caution vs. warning vs. important

Ted
I didn't realize that signs were that different internationally. Based on that it seems that you would use the colors and symbols that are standard to the industry that you are documenting.

- Ted @TedAtCIS