This self-study course helps you write clearer, more effective error messages, whether they appear in IDEs, command lines, or GUIs. While this course contains lessons for many error message scenarios, the majority of examples and guidance focus on developer-facing error messages.
Note: Not all guidelines presented in this course are appropriate in every situation for every target audience. Always aim error messages at the product’s target audience.
Target audience for this course
We’ve aimed this course at the following audiences:
- Engineers
- Program managers
- Technical writers
We recommend taking Technical Writing One before taking this error messages course. After all, good error messages are just another form of good technical writing. If you’d prefer to skip Technical Writing One for now, that’s okay—you can still benefit from this error messages course.
Why take this course?
Bad error messages frustrate users. Good error messages provide critical information when things are not working as expected. Error messages are often the main way developers interact with users when problems occur. Some error messages are caused by invalid user inputs or misuse of certain features and some are caused by product defects; all error messages require users to figure out what to do next.
Data collected through Google support systems and UX research identified the following common problems with bad error messages:
- unactionable
- vague
- imprecise
- confusing
- inaccurate
- unclear cause
- unknown next steps
Conversely, good error messages provide the following benefits:
- Deliver the best user experience.
- Are actionable.
- Are universally accessible. (To learn more, take Tech Writing for Accessibility.)
- Enable users to help themselves.
- Reduce the support workload.
- Enable faster resolution of issues.
Learning objectives
After completing this class, you will know how to do the following:
- Write clearer, more helpful error messages.
- Review your teammates’ error messages.
Learning non-objectives
This course does not explain the mechanics of generating error messages. For example, this course does not explain how to display error messages within a GUI.
This course in ten seconds
Great error messages answer two questions as clearly and concisely as possible:
- What went wrong?
- How does the user fix that problem?
Yes, it’s just that simple.
And, it’s just that hard.