Error Handling Guidelines
We need to keep error messages consistent and user-friendly. When handling a new error case, the following guidelines should be followed.
"Established wisdom holds that good error messages are polite, precise, and constructive. The Web brings a few new guidelines: Make error messages clearly visible, reduce the work required to fix the problem, and educate users along the way." ― Nielsen Norman Group,
Design Principles
First and foremost, if a problem occurs, it should fail gracefully if possible. This means that the product should not be brittle. Functions should be fail-safed by including fall back actions and retries. Displaying errors to the user should only happen in exceptional cases where the prior actions repeatedly fail.
Purpose
Error messages should be purposeful, achieving the following goals:
Awareness
Action
Education
User Experience
In general, we want to enhance UX where possible. This includes:
Error message copy
A human description is a detailed description of what happened and why. It should be:
Explicit
Needs to include what went wrong as well as reasons why
Polite
Must not put blame on the user or imply they are wrong
Precise
Must be specific to the erroneous event that occurred
A human action is an actionable item the user can take and should be:
Descriptive
Needs to be precise on what the user can do - use steps if necessary. Assume that the user has no idea what they are doing.
Educational
We should take this time to educate the user on the process of how to perform the task(s) properly to reduce future occurrences. We can do this by providing steps as before or linking the user to an appropriate article.
Note that for every error, there should be more than one action that the user can take. Usually, there will be an action for contacting support and searching the knowledge base for more information. These guidelines should also be used when writing additional information that will be used by support.