warnings, cautions, notes in sw documentation

Simon North simonxml at gmail.com
Tue Aug 2 08:18:17 PDT 2011


All the answers I have seen so far seem to relate to HARDWARE.
In a SOFTWARE context, I think it's much more common to
use something like the following (this is my wording, so no official):

Warning: an irrecoverable action (formatting a disk), permanent data
loss or other
action that may result in an irreversible change to the system (such
as deleting a user
account) or damage to the hardware

Caution: an action that may seriously affect system performance (memory usage),
make take an extremely long time (resulting in inability to use the
system), may
seriously affect the system integrity (like removing password control
or disabling a
firewall) or loss or changes as listed for a warning that are reversible.

Note: an action that may result in inconvenience or confusion or,
positively, actions
that may make usage easier.

Regards, Simon North
Technical Writer, Quintiq.



More information about the framers mailing list