the arcane craft of writing error messages
Let me put forth an axiom: software development is hard. It's not just the coding bits that are hard -- they are, don't get me wrong, it's just that coding isn't the only thing that's hard about software development. There's more to software development than the coding, which is why software development has a bevy of non-coders working on the software.
One of the things that's surprisingly difficult about software development is crafting the error messages. (A second axiom, since I'm feeling axiomatic today: Software has bugs and unexpected problems that it can't handle on its own.) Error messages are so notiously bad that we make jokes about them, write error messages in haiku, and allow you to generate your own.
I've been reminded of how difficult it is to write good error messages a couple of times last week. I reviewed the error messages for RDC v2, which has its own challenges inherent in writing its error messages. Just think of all of the reasons that you might not be able to connect from your Mac to a Windows box, and figure out how to document them in a way such that the user can do something about it (if, in fact, there is something that the user can do). I really don't envy our user assistance team.
In the middle of that review, I've been using Pandora lately. I haven't been keeping music or podcasts on my work laptop (that's all been moved over to my Mac Mini in my office, since people seem to like my shared iTunes library), but I need something to listen to when I'm on the road. Pandora to the rescue. The problem with Pandora is that it requires a solid Internet connection, and my last hotel gave me anything but a stable Internet link. So when it ran into problems when I asked it to add another artist to my newest Pandora station, it gave me the following error message:
I'm sorry, I had a small problem while looking for that music. It's my fault.
[try again]
I actually exclaimed, 'oooh!' out loud. I felt bad for the app, felt guilty for making it think that it was the app's fault. What a great error message! I didn't get upset or frustrated. For an app like this, the tone is just right. They don't need formal-sounding error messages, it's a nice little casual app, and friendliness is important for it.
So what's important in writing error messages? Don't tell the user that error 448115490235 just happened or that some generic system error happened, tell them the actual problem. Even better, tell them what they can do to try to fix it or at least troubleshoot the problem. Use the right words and a tone that's appropriate for your audience.
This all sounds easy enough, but it turns out it's not. Software engineers are notoriously bad at this kind of thing (nothing against you code monkeys out there!), which is why there's so many really bad error messages out there. Kudos to the Pandora folks for doing a pretty good job of it.
Comments
Anonymous
February 05, 2007
The comment has been removedAnonymous
February 05, 2007
<i>I reviewed the error messages for RDC v2</i> YAAAAY Tease. Here, in honor of 1-30-07 (NEVER FORGET!): http://www.dyewell.com/saveboston/Anonymous
February 05, 2007
The comment has been removedAnonymous
February 05, 2007
[url=http://tramadol-hgf65.blogspot.com/]tramadol[/url] http://tramadol-hgf65.blogspot.com/ Ciao!Anonymous
February 05, 2007
Good old RDC. I hope that the next version doesn't have one of the wonderful bugs the current one does: fail to connect once, (i.e. because something isn't ready, you entered the wrong server, you forgot to sacrifice a goat, whatever) and no further connections will work until you quit it and start it again. Joy! Error messages are hard. Not least of all if you don't actually know what caused it. "Well yes, the we failed to get that... but is it because it doesn't exist? Or did something else happen? Maybe you forgot to sacrifice a goat..."Anonymous
February 05, 2007
The comment has been removedAnonymous
February 06, 2007
Just in case you thought those arcane error messages (e.g., error 448115490235) are bad, at least they generally convey some information. Even if the significantly-above-average informed customer won't know what it is, theoretically a support person might and would be able to help them out. (And when I mention a support person, I don't generally think of PSS, but rather the developer on the product, since PSS doesn't know these numbers either, except by frequency of hearing from customers that they hit error #448115490235, and then they plead with the development team to fix the problem or help them find a workaround to write in a KB article.) My favorite errors are the ones when a whole class of error conditions is arbitrarily summarized. e.g., One part of the system returns error codes in number format (which may even have a direct translation to error messages provided to you by the system), but since the code that uses that system returns a different set of error codes to its clients, all errors from that system get one error code. All of a sudden, you go from a wealth of information that might help a developer, or even the user(!) to solve the problem, down to an inconvenient error message (e.g., error 1) that refers to so many possible problems that no simple text could direct the user how to fix it, and that no support person, all the way back to the developer, can figure out what happened on the user's machine. While I agree that these numeric error codes need to be translated into (1) informative error messages, (2) directions on what action to take to solve the problem, and maybe even (3) feedback to Microsoft as to how to better address one or more aspects of a particular problem, what I don't agree with is the tendency to UA folks to say something along the lines of, "If you can only have an error number, better not to show anything, as it will confuse the user." On the contrary, it might be the only thing that will help them get any help, even if it does mean it might take customer service interaction and a software revision to get it to them. -nhAnonymous
February 06, 2007
"John - It's not teasing when you already know that it's coming. If I were going to tease you, ... Heh. No, I'll stop right there. :)" Bad Nadyne! Wicked Nadyne! Wicked Evil Nadyne! Next you'll be hanging up the Grail-Shaped lantern!Anonymous
February 08, 2007
[deleted Asam's latest trolling]Anonymous
February 08, 2007
The comment has been removedAnonymous
February 08, 2007
The comment has been removedAnonymous
February 08, 2007
The comment has been removedAnonymous
February 08, 2007
The comment has been removedAnonymous
February 08, 2007
The comment has been removedAnonymous
February 08, 2007
The comment has been removedAnonymous
February 11, 2007
The comment has been removedAnonymous
February 12, 2007
BCS - Thanks for that feedback. I sent it along to our User Assistance team so that they can take a look at it and make sure that we're giving you better error messages in the future.Anonymous
February 13, 2007
The ones I hate are the ones that are accurate, but so vague as to be useless" "Some messages were deleted" What, just now, when I hit "Delete"? How is that an error, I did it. They were deleted by the server? A hamster? I think sometimes a grammarian would be a good editor for error messages.Anonymous
February 16, 2007
What are the non-coding jobs in computer science?