I want to spend a few minutes talking about three types of special statements found in most technical content:
Notes, cautions, and warnings are statements that serve a special purpose. They contain a sentence (or possibly two) that you want your readers to pay particular attention to. The information in one of these statements is meant to stand out.
When used correctly and consistently, special statements are a great way to provide key information to readers.
When used incorrectly and inconsistently, readers completely ignore them, thus defeating their purpose.
Pick a Use and Stick to It
The first thing to decide about special statements is how you will use each category. What type of information goes into a note? A caution? A warning? What really is the difference between a caution and a warning? Most companies that I work with have not defined caution versus warning, and similar information ends up in each.
In fact, I have seen content where the same statement is contained in a note, a caution, and a warning. This is confusing at best. For writers to use statements properly, there can be no uncertainty on how each is used.
Most companies use the three statements as follows:
- Note – Information that is supplemental or needs to be noticed for a reason that does not fall into caution or warning. I know, that looks kind of funny. But notes are usually used as the catch-all for information that the writer thinks are particularly important. Perhaps it is a hint or a tip. A note is the least critical statement.
- Caution – Information that indicates a problem can occur if the reader doesn’t pay attention. Most often I’ve seen this statement used to indicate a piece of equipment can break if the caution is not followed. A caution is considered more important or severe than a note, but not as important or severe as a warning.
- Warning – Information that, if not followed, will create grave danger or bodily harm. If a warning is ignored, the user of the equipment could be injured or even killed. A warning is the most important statement in technical writing.
If your company is going to use notes, cautions, and warnings, agree on the usage of each and write it down. Provide several examples of the most common ones you use. And make sure everyone uses them consistently.
Limit the Use of Special Statements
I’ve worked with many customers over the years who use special statements all the time. And I mean all the time. Every page has at least one special statement. These companies often have more varieties of special statements. In addition to notes, cautions, and warnings they have tips, time-savers, hints, and good-to-knows.
Here’s the thing about special statements: When you overuse them, they are ignored. Overusing special statements, or having too many types, causes reader fatigue. The desire to read information that has been called out goes away. When everything is special, nothing is special.
Limit the types of statements you have and limit using their use to only when necessary.
Special statements are always separated from the main content. There are a variety of ways to format them so they stand out. Here are ones off the top of my head:
- Put space around them
- Indent them on one or both sides
- Put a box around them
- Use italics
- Use shading or a special color for the box or text
- Use an icon
When it comes to formatting, less is more. If you use all the formatting above (and you can use all of them at once), the statement will be so busy that no one will read it. The eye will take one glance at it and the brain will quickly move on to something easier to read.
Make sure that you apply the formatting consistently to each statement. Don’t use a box for some and an indent for others. All statements should look like statements.
Most companies use different icons for each statement. This is important. People need to be able to distinguish a note that has some helpful information from a warning that could cause them to be injured. But just like with the text, minimize the number of icons you use and use each icon consistently.
Keep them Short
Nothing sends the eye moving to the next block of text than a length note, caution, or warning. This is particularly true if you’ve applied lots of formatting. If your special statement is:
- In a shaded box
And if the special statement contains more than one or two sentences, there is a high likelihood it will be ignored. Get to the point of the statement immediately. Couching statements in additional information just makes them into paragraphs. If your statement is a paragraph, then make it a paragraph.
The point of using a special statement is to get readers to pay attention to it. The onus is on the writer to do everything they can to make a special statement easy to locate, easy to understand, and easy to read.
Content Rules has decades of experience helping customers govern and manage their content so they can provide the right information at the right time. If you are considering breaking free of the document paradigm, contact us. We can help you avoid the pitfalls and achieve success in your journey to content management.