Special notices are an important feature of professional technical writing: they highlight special information readers need to know to understand what they are reading, to accomplish what they want to do, to prevent damage to equipment, and to keep from hurting themselves or others.
Very special notices. State-of-the-art notices with clever comments.
Guidelines for Specific Types of Notices
This chapter presents a a specific style of notices. Be very aware that other styles and formats exist.
- Use special notices to emphasize key points or warn or caution readers about damage or injury.
- Be careful to use the types of special notices precisely, for their defined purposes. Use the four types of special notices in the following ways:
Note—To emphasize points or reminders, or to indicate minor problems in a procedure.
Caution—To warn readers about possible damage to equipment or data, about potential problems in the outcome of what they are doing, or potential negative experiences (such as embarrassment).
Warning—To warn readers about the possibility of minor injury to themselves or others.
Danger—To warn readers about the possibility of serious or fatal injury to themselves or others.
Note: Take a look around your garage or kitchen, and look at the special notices you see on products. You will see plenty of variation, which is likely to be dependent on specific industry or corporate standards.
Deciding on which type of notice to use is not an exact science. Just don't use a danger notice when a warning is more appropriate (the same as "crying wolf"). Also, use notices in a consistent way throughout a document. Do not create your own notices, such as putting "Important:" in place of "Warning."
- Place special notices at the point in text where they are needed. For example, place a caution or danger notice just before or just after discussing a step in which readers might hurt themselves.
- Avoid having too many special notices at any one point in the text. Otherwise, the effectiveness of their special format will be lost. (If you have too many, combine them.)
- With warnings, cautions, and danger notices, explain the consequences of not paying attention to the notice. State what will happen if the reader does not heed the notice.
- The examples in this section use bold. Avoid all-caps for the text of any special notice.
Note: In a properly set up publishing area, tech writers would not have to decide which type of notice to use or even craft notice language. That should be the job of organization attorneys. Still, those attorneys might be too busy to review your notices, and so the burden may still be on you the technical writer or editor.
Format for Special Notices
Use the following for specific details on the capitalization, typography (bold, underlining, different fonts, different types sizes), and spacing for each type of special notice.
Use the following format for simple notes:
- Type the label "Note" followed by a colon. (Although some of the following examples use bold, prefer italics to prevent visual confusion with headings.)
- Begin typing the text of the note one space after the colon. (But don't put the text of the note in bold or italics.)
- Singlespace within the text of the note; skip one line above and below the note.
- Start run-over lines on the regular left margin.
- Align the note with the text to which it refers (as illustrated in the second example).
Example of a simple note
Example of a note within a bulleted list (not regular running text). This same principle (that special notices align to the text they refer to) applies to the other types of special notices as well.
Use the following format for multiple notes:
- Use this format when you have so many notes that they would distracting to present individually.
- Type the label "Notes" followed by a colon. (Although some of the following examples use bold, prefer italics to prevent visual confusion with headings.)
- Use a numbered list for the individual notes; in it, follow the rules for numbered lists. (Do not use bold or italics for the individual notes.)
- Align the notes with the text to which the refer; skip the equivalent of one line above and below the notes.
Example of a multiple note. Use this format if you have lots of notes and want to collect them all in one place to prevent distraction.
Use the following format for warnings:
- Type the label "Warning," italicize it, and follow it with a colon.
- Either tab to beginning of the text of the warning, or use the hanging-indent format (which is much better). The hanging-indent format for the warning in the example below uses 0.63 inches for both the tab and the hanging indent, but font sizes will cause this value to vary.
- Use regular body font for the text of the warning notice (no bold, no italics, no all-caps, no color).
- Align the warning notice with the text it refers to.
- Skip the equivalent of one line above and below the warning notice.
Example of a warning notice. Use this one to alert readers to the possibility of minor injury.
Use the following format for caution notices:
- Type the label "Caution" follow it with a colon, and bold both the label and the colon.
- Skip one line and begin the text of the caution aligned with the start of the caution label.
- Singlespace the text of the caution; skip one line above and below the notice.
- Align the caution notice with the text it refers to (in the preceding, the warning notice occurs within a numbered list and is indented accordingly).
Example of a caution notice. Use this one to alert readers of possible damage to equipment or problems with the procedure.
Use the following format for danger notices:
- Type the label "DANGER" in all-caps bold.
- Align the danger notice with the text it refers to.
- Singlespace the text of the danger notice; skip one line above and below the danger notice.
- Use bold on the text of the danger notice if you have it (but never all-caps).
- If you have graphics capability, draw a box around the danger notice (including the label).
Danger notice. Use this one to alert readers of the possibility of serious injury or fatality.
Other Formatting Issues
Here are some additional points to consider concerning special notices:
Special alignment. Special notices must align to the text to which they refer. For example, if you have a note that adds some special detail to something in a bulleted list item, you must align that note to the text of the bulleted item. Of course, if the note follows a bulleted list but refers to the whole list, then you can use the regular left margin.
Single spaced text. All of the examples and discussion in this unit are based on single spaced text. Leave either one blank line between running text and special notices—depending on what looks best to you. (And of course both running text and the text of the special notices would be single spaced.)
Placement of special notices. Place special notices just before or just after the point at which they are relevant. For example, you can warn readers to back up all data before you tell them to reformat their hard drive. However, in practice serious special notices are placed at the very beginning of a procedure where great harm to data, equipment, or people is likely to occur.
One technique used by very cautious writers (maybe those who have been burned) is to place all serious notices (warnings, cautions, and dangers) somewhere at the beginning of the document, and then repeat them individually where they apply. An organization is likely to have a style guide that states requirements on placement of notices.
Multiple special notices. You run into situations where you have three or four special notices, all jammed together in the same part of the text, each one following another. This is a problem because the whole point of the special formatting of the notices is lost: something is special because it is different from the surrounding. The solution to this problem is to create one identifying heading (for example, "Notes and Warnings"), and then list the notices (either bulleted or numbered) below it.
I would appreciate your thoughts, reactions, criticism regarding this chapter: your response—David McMurrey.