Archive for December, 2010

Tips on creating Notes, Cautions and Warnings!!


There are three things in a technical document that you need to write carefully and present consistently: Notes, Cautions, and Warnings, in that order of severity.

A Note is the least severe of all prompts. There is no risk of system failure or any damage to the system. It’s helpful hint,
sometimes a tip, to help the user work more efficiently.

Without a note a user may lose precious time 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.”

A Caution is a more serious prompt. It 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 is 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.”

A Warning is the highest level of alert. 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. For example:

“WARNING: Removing the capacitor C125 without first grounding the motherboard may lead to electrocution and death!”

It is 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 cross bones icon, all other warnings should also look like that.

Consistency creates trust and helps the comprehension and retention of your subject matter.

Before signing off…

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 secure technical writing job in high-demand can be habit forming!

Advertisements