Highlighting Hazards:
Mastering Warnings and Error Messages

by Carrie Spira, Quill Contributor

Presented by Leah Guren

Wednesday, December 8, 2004 at CheckFree –i Solutions

What is a Hazard?

Any potential problem a user can avoid by specifically doing, or avoiding, an action.
-Or-
Any unusual or unexpected behaviour that can interfere with normal usage.

Well-Documented Hazards…

Alert readers to potential problems to prevent serious damage, injury, or loss of life.
Provide critical information at the right time.
Protect the company by addressing product liability requirements.

…when the reader notices, perceives, understands, and chooses to comply with the warning.

Poorly-Documented Hazards…

Exist to satisfy an industry standard.
State the obvious or the asinine.
Exaggerate hazard issues.
Include weak, ineffective content or icons.

Key Elements of Hazards

Signal Word	Use standard signals only: Danger, Warning, Caution, Note, or Tip. Readers may not understand the difference between warnings and cautions, so pick one and use it consistently.
Action	Use active, direct voice, and the strongest verb available. Emphasize a positive action, where practical. Be concise yet clear.
Ramifications	Document the connection between the action and the problem (the "so what?" details) to improve reader compliance.
Recovery (optional)	Include recovery steps, where practical.

Hazard Placement and Formatting

Position before a potential danger, but close enough to be relevant. Repeat critical hazards where needed instead of cross-referencing to hazard content.

When formatting hazards:

Set signal word apart with white space.
Use a hanging indent paragraph and a sans-serif font for maximum readability.
Box or shade background to visually chunk the hazard component.
Consider using colour to differentiate hazard content from body content.
Indent to indicate hierarchy and relationships to body content.

Hazard Example

Certification and Compliance Considerations

Specialized markets and industries require that hazards comply with specific certification standards and guidelines. Legal issues can be complex and require sign-offs by appropriate stakeholders. Identify your internal resources and research the latest version of the standard to make sure your documentation meets certification requirements.

Error Messages

Error messages are a particular kind of warning that appear in documentation or as part of an application. They address unusual or exceptional conditions that the product can't resolve.

Good error messages…

Teach users about the problem.
Enable the user to recover from a problem.
Appear in both the product documentation and the product.

Poor error messages are…

Expensive to both users and the company.
Frustrating and dissatisfying for users.
Bypassed and disregarded by users.
Often written by developers, programmers, or engineers whose job focus is on product functionality, and not the user.

Key Elements of Error Messages

Identification	Specific number or code the user can communicate to the company for internal technical support reporting.
Problem	Detail the most likely cause(s) first.
Cause	Include recovery steps, where practical.
Corrective Action	Include a recovery procedure. Balance audience needs against complexity. Consider screen accessibility and readability. Consider linking to an online help system or Web site knowledge base.

Error Message Example

About Carrie Spira

Carrie has a BA in Rhetoric and Professional Writing from the University of Waterloo. She lives in Kitchener with her family and works as a Technical Writer in Waterloo. Carrie enjoys puttering in her gardens, experimenting with digital photography, and makes time for cardio and weight training activities at the YMCA most days after work.

In this issue:

Highlighting Hazards: Mastering Warnings and Error Messages