Nobody is keen to invest in error messages. And by invest I mean energy, money, man hours … Declare “Our product will excel at failing gracefully”, and you can probably count on your stakeholders to drop off after “excel at failing”.
Everybody fails (sometimes)
But every. Product. Fails. Networks happen, unexpected input happens, integrations with other products happen. The real world happens, and what do we do then?
My last post about unhelpful error messages sparked some interesting comments and discussion, on the blog and in the Technical Writer in Action LinkedIn group, including a lot of good points about what fellow tech writers consider to be good qualities in an error message. I said I would follow up my post with a more constructive take, and here it is.
1. Fight the power (push back, fix the code)
Rewriting error messages often runs the risk of being lipstick on the proverbial pig. Sometimes it’s all we can do as writers short term to improve the writing, but we shouldn’t be scared to push back and look at whether the product is behaving as it should in the first place:
- Could the error be prevented before it happens? For example, improve the UI to prevent users from entering invalid input, highlight required fields, and so on.
- Is the error displayed to the right users? Misconfiguration in the backend should raise a ticket for whoever configures the backend, rather than cause ugly error messages for the end user who can do nothing about it. Messages that essentially say “Contact your administrator” should rather say “Your administrator has been contacted”.
- Is one error message enough? One of my most frequent requests is actually more error messages. For users, more messages can actually be a good thing, because they allow us to be more specific. Too often, developers create catchall messages that cover so many scenarios it is close to impossible to give users instructions of any value. A shocking amount of error messages can be paraphrased as: “This, that, or the other may have happened. Try 547 different configuration changes, or wait an hour or two and it may have gone away.” Not helpful.
2. Find out what it means to me (respect the user, be instructive)
Good error messages are respectful of users and their time. Conciseness is a value in and of itself. Users read this stuff to do, they don’t read to learn. For this reason, I find that going into detail on exactly what has happened is often not the best use of screen space and user attention.
For the user to be able to do, the message must be instructive. An instructive message focuses on why the user should care about this message, and either give them reassurance that someone else will fix the problem, or give them the information they need to act themselves.
This information needs to be:
- specific
- inclusive enough that it doesn’t entirely exclude potential scenarios. Few things are more frustrating than following instructions that turn out to have no relevance.
When working on pop-up messages, I always try to pay attention to the buttons as well, and aim for descriptive action verbs. Users may find having to click “OK” after reading about a critical error downright offensive, and it does not tell them what happens once they have clicked the button, either.
3. Only when I laugh (don’t try for funny)
A final word of advice: don’t try to be cute or funny.
I have seen several people insist, after my previous post about humor and error messages, that it’s fun and appropriate if the error isn’t very serious, such as a 404 not found message.
Instead of reiterating my first rant, let me tell you a story:
A few months ago, I visited a newly overhauled website that was boasting about its new backend and look and feel. I tried to use the site search, but clicking on links in my search results repeatedly took me to a “hilarious” new 404. Clearly, some pages had gone missing in their migration to a new platform. These things happen, of course, but “funny” not found pages pretty much assume that the user has clicked on a random rotten link or entered a wrong URL. In my case, I could not find the content that the site’s own search results promised. My frustration was mounting. Spare me the jokes!
Point of the story: it’s hard to predict all the scenarios and situations users will be in when they see our error messages. It is, in fact, about respect. You show it, or you lose it.
That’s what it’s all about
Creating helpful error messages can be very hard, but it’s so worth it. I would say it’s about the best use of a technical communicator’s time I can think of. Troubleshooting is where users tend to get the most frustrated, and better instructions in the product simplify troubleshooting. Less frustration, happier users. And happier users is what we should be all about.
(Photo by Gerry Balding on Flickr)