doc/collaboration/documentation/notices.rst

.. _notices:

Notices: Notes, Cautions, Warnings, and Dangers
###############################################

We use four special types of notices: notes, cautions, warnings, and
dangers. Here are some specific rules and tips with regard to these
notices:

* Do not use a notice directly after a heading. Notices must follow a
  variant of body text.
* Avoid back-to-back notices.
* To improve readability, rewrite content to eliminate multiple
  notices in a single module.
* If there is no clean way to avoid using back-to-back notices, use a
  different style or multiple paragraphs, for example, combine two
  notes into one or separate them with body text.

Notes
*****

Use notes sparingly. Avoid having more than one note per subsection. If
you exceed this number consistently, consider rewriting the notes as
main body text. Example:

.. note::
   A note is supposed to provide supplemental information, not
   emphasized information.



Cautions, Warnings, and Dangers
*******************************

Tell readers what will happen if they do not heed cautions or warnings,
circuits will fry, electrical shock may kill you, etc.

* Use "Caution" to identify hazards resulting in property damage
  accidents, including data loss. Also use "Caution" to alert against
  unsafe practices.
* Use "Warning" and "Danger" for property damage accidents only if
  personal injury risk appropriate to these levels is also involved.

These are examples of typical notices, the correct syntax and the
conditions for their usage:

.. note::
   Notes are ancillary bits of information, subordinate to the main
   flow. Reserve the note tag for information that does not readily
   flow with the main text but which you want to set apart for one
   reason or another. Notes should be relatively short. If there is
   more than enough information to warrant a short paragraph,
   consider rewriting the note as body text.

.. caution::
   Cautions are low-level hazard messages that alert the user of
   possible equipment, product, and software damage, including loss
   of data. Cautions typically appear as a yellow triangle with a
   black exclamation point.

.. warning::
   Warnings are mid-level hazards (more serious than cautions) that
   are likely to cause product damage as well as bodily injury to
   humans. Warnings may appear in a black triangle with orange hazard-
   specific graphics for warnings (or with the colors reversed). The
   most common warning is for electrical hazards, but there are many
   other hazard-specific graphics.

.. danger::
   Dangers are high-level hazards that are likely to cause product
   damage as well as bodily injury and even death to humans. Dangers
   use a red triangle with white (and black) hazard-specific
   graphics, the same as found on warnings.