Latest posts by techwriter (see all)
- Test Your Knowledge of 4 Basic Fonts – Drag & Drop - January 27, 2017
- How NOT to Design a Web Site - January 25, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
© Ugur Akinci
You can hurt or at least drive your readers crazy if you neglect the following three components of a technical document:
A Note is the least severe of all these three prompts.
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.”
A Caution is a more serious prompt.
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.
“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. This is serious stuff!
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.
“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 cross bones icon, all other warnings should also look like that.
Consistency creates trust and helps the comprehension and retention of your subject matter.
So before I sign off, 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.
P.S. Do you have any questions about this topic or anything else? Please hit the REPLY button and let me know what you think. Thanks!
(Free photo courtesy of morguefile-dot-com)