Precautionary statements are sentences interjected in the middle of a technical documentation. Their purposes are to divert the reader’s attention to emphasis something ideally short they need or should know about. Often, most people writing a precautionary statement would use:
NOTE: SOME SENTENCE HERE
The drawback of using the word “NOTE:” is that it provides limited context. Here are a list of precautionary statement words that provide much more context :
— DANGER : Used when there is a serious irreversible risk to a company’s financial health or an fatal risk to an individual’s physical health. Also used when the law is involved.
— (PERFORMANCE/HARDWARE) CAUTION/WARNING : Used when there is any form of risk that can damage a company’s situation. It is assumed that the risk can be endured/mitigated/managed.
— RISK : Used when we don’t know the unintended consequences of an action
— (PERFORMANCE/HARDWARE/COST) TIP : Used when there is something the user CAN do to improve their experience with a product but not absolutely needed
— RECOMMENDED : Used as a placeholder for TIP that doesn’t have a quantitative measurement yet.
— REQUIRED: Used when there is a prerequisite that a user MUST fulfill.
— IMPORTANT : Used when there is a prerequisite that a user should fulfill but don’t absolutely need to.
— REMINDER: Used when there is something the user should know about before making a decision
— LIMITATION : Used when we need to inform the user of any thresholds they should know about before making a decision
— INCOMING/INDICATION : Used when the user should expect something after making a decision
— RESTRICTION : Asking the user not to do something
— ATTENTION : For all other scenarios yet to be better classified
In the case that an article will have a lot of precautionary statements, it is better to write them all as a section instead. For example, if an article will have many REQUIRED, it is better to just write a prerequisite section. Remember that precautionary statements are meant to temporarily emphasis the reader on a certain content. Too much emphasis will create the effect that nothing is emphasized.
What is the difference between caution/warning?
Historically, in chemistry, warning is a stronger level than caution. However in the context of computer technology, they don’t really have that much difference. It’s better to just stick with one of them and use DANGER for extreme cases.
What is the difference between TIP/RECOMMENDED?
TIP is used when we can provide advice in a specific category (performance, cost, memory usage) that helps the user in that same category. RECOMMENDED is when the specific category hasn’t been established yet.
