Posted by Ted on
URL: https://discuss.asciidoctor.org/Documentation-question-caution-vs-warning-vs-important-tp6050.html

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?