How to Write Notes, Cautions, and Warnings
Introduction
How to write notes, cautions, and warnings is an important skill in documentation. They can be used to make a point clear or to warn the reader about something they should be careful about or the possibility of personal injury.
You can hurt or at least drive your readers crazy if you neglect the following three components of a technical document:
- Notes
- Cautions
- Warnings
NOTE
A Note is the least severe of all these three prompts.
Notes are used when the writer wants to add something that is not essential for the understanding of the text but which they want to add for their own convenience.
There is no risk of system failure or any damage to the system.
A note is a helpful hint, sometimes a tip, to help the user work more efficiently.
Without a note, a user may lose precious time and get frustrated while trying to understand why something is not working.
You can prevent that by adding a note like the following:
“NOTE: Make sure the system is turned on and running for at least 7 minutes before you slide Lever R4 from right to left.”
CAUTION
A caution is a more serious prompt.
Cautions are used when there is a danger that readers may misunderstand what has been written and thereby cause themselves harm.
Important Information: A caution points at a POSSIBLE development that may or may not end up in system failure, business problem, or physical damage.
It brings up an issue that the user would better pay attention to, even if it’s not a life-or-death matter.
For example:
“CAUTION: if you do not obtain prior permission from the site manager to conduct an inspection you can be sued for trespassing and criminal conduct.”
WARNING
A Warning is the highest level of alert. This is serious stuff!
Warnings are used when there is a danger that readers may misunderstand what has been written and thereby cause personal injury.
Important Information: The stakes are much higher and it COULD be a matter of life-and-death.
Any PROBABLE equipment or site damage deserves a clear warning.
To create an effective warning message, the following are some pointers to follow.
- Keep it short and simple- The reader should be able to get the message in less than a minute of reading.
- Use strong, direct language- Write in a way that will grab the attention of your readers and make them listen to what you have to say.
- Give detailed descriptions- Be specific about what will happen and why it is happening.
- Use proper punctuation – use periods and commas for clarity and use semicolons appropriately.
For example:
“WARNING: Removing the capacitor C125 without first grounding the motherboard may lead to electrocution and death!”
It’s excellent practice to present these alerts with their own ICONS so that at one look the reader can understand its level of severity.
Make sure you present these prompts always in the same format.
If, for example, you present your first NOTE in the sidebar, present all other notes also in the sidebar.
If you present your first WARNING in red letters accompanied by a skull and crossbones icon, all other warnings should also look like that.
Consistency creates trust and helps the comprehension and retention of your subject matter.
Conclusion
So before I sign off on notes, cautions, warnings, let me add:
- NOTE: You are in the process of building yourself a great future as a technical writer.
- CAUTION: Just like I did, you may also kick yourself for not having tried it earlier.
- WARNING: A well-paying technical writing job can be habit-forming!
Write tight. Stay bright. Serve right.
RESOURCES
How to Write a Software “Release Notes” Document
What is Documentation? (Wikipedia)
MORE INFO
