Writing good error messages which help users understand how to use the system is difficult. Often we get bug reports stating "Error message x is confusing" which usually sparks a long debate in the team over how to reword it.

Are there any good resources out there about how to write good error messages.

Im looking for

  • books
  • Good blog posts articles
  • papers
  • research results

Many design books mention it but only devote a few paragraphs to it.

  • 1
    Get someone in your organization that didn't develop the software to use (abuse) the software and see what they say. Also, an error message should tell the user how to fix the problem, not just report a problem. – Gilbert Le Blanc Sep 20 '11 at 13:14

Defensive Design for the Web: How to Improve Error Messages, Help, Forms, and Other Crisis Points (2004) by 37signals, while outdated in 2011, does show you various examples of bad error handling, including copy, and explains what's wrong and how to improve. It calls all this "contingency design" (the title of the book is inspired by the concept of defensive driving). Some of the patterns extracted are still relevant today. Notably Amazon was a leader in this area way back then.

The biggest thing I took away from it when I read it back then was that your site should behave like a salesman in a store: if I'm lost or I can't find an item, the salesman will ask me questions to help me find what I'm looking for whereas most websites will just say "Not found" and that's it. Here's an excerpt from the opening chapter:

This book will show you how to use contingency design to improve your site's usability. You'll learn the following:

  • What contingency design is and why it's important
  • 40 guidelines that will help you prevent errors and rescue customers when things go wrong
  • How to make error recovery and prevention part of your long-term design process
  • How to evaluate your site's contingency design so you can focus on the areas that need help most

Overall the book is useful in designing error handling in your site or app, but there are some good points made specifically about copy as well. From chapter two, "Show the problem: display obvious error messages and alerts":

A good error message lets a customer instantly know:

  • That an error occurred
  • What the error is
  • How to recover

The chapter contains a huge number of examples (from 2003) of sites (many of which no longer exist). Each discussion point includes examples of sites doing things the wrong way and why, and examples of sites doing things well and why.

  • 2
    Smashing Magazine: Getting Started With Defensive Web Design cites that book as a resource + Bulletproof Web Design, by Dan Cederholm which is about Contingency Design, 3rd edition (HTML5 and CSS3) due out end of this year. For further information, this reviewer rates the second book over the former. – Roger Attrill Sep 20 '11 at 12:37
  • 1
    @Roger Two different (unrelated) kinds of contingency design. Defensive Web Design is about contingency design at a high level; eg. how do you design your app/site to deal with contingencies like "this item is not available". Bulletproof Web Design is about implementation, specifically CSS, and gives you concrete HTML/CSS examples relating to how to design for contingencies like unsupported browsers. – Rahul Sep 20 '11 at 13:15
  • Will look into this book... How about web sites and or blogs... is there anything out there? – Mark Sep 21 '11 at 9:20

I was also searching for good resources on writing effective error messages. The most useful set of resources I've found were from microsoft:

I've also found that the Microsoft Manual of Style had some interesting parts that could be applied to error messages. It's worth the read if you are interested in creating documentation, but it's a long (and probably boring) read if you are only interested in how to write good error messages.

Since I spend most of my time writing and reviewing error messages, I personally think that a good error message should have 3 parts:

  • The Problem
  • The Cause
  • The Solution

First concentrate on writing these three parts down, and then edit the text to make it smaller and more humane. I've written a post on how to write error messages, but if you nailed these three parts in your message, you already solved 80% of the problem.

Not the answer you're looking for? Browse other questions tagged or ask your own question.