Category: Technical Communications

Categories
Technical Communications Usability

The Three Most Annoying And Least Helpful Types Of Error Messages

Avoid annoying your users, focus on being helpful

Error messages are a constant source of frustration to users of all skill levels. A recent example is Don Norman’s rant Error Message Are Evil (sic) on LinkedIn, where he insists that error messages must start collaborating with the users, and that software needs to become better at anticipating and accommodating actual user behavior. As someone who is often tasked with the writing and rewriting of error messages, it’s hard not to agree.

Here are the three most common unhelpful types of error messages that I know of, and what makes them unbearably annoying to me.

1. Written for the developers: Object reference not set to an instance of an object

Of all error messages that should not go out to end users, this example is probably my least favorite. Someone really should just change the standard nullpointerexception error with something more readable to a user, once and for all. “Developer malfunction”, perhaps. I kid, but only just. And there are many more messages that follow a similar logic.

All too often, internal error messages trickle out to users from frameworks, APIs, or deep dark places in code that nobody every intended to expose. They are usually hardcoded and hold no information that the user can make sense of, or wrap a tiny piece of readable information in noise. Typically, they also use words like “illegal”, making any normal person think a crime has been committed, rather than the use of a character that couldn’t be parsed.

2. Well, duh: Unexpected error

Ohhhh, so you didn’t see this one coming, application? Well, that’s helpful for me as a user to know. And now what?

The literal “Unexpected error” is quite common, but there are tons of messages out there that are at about the same level of helpfulness once you’ve read them. Telling the user at least something they don’t already know is a very basic criterion for an error message. And they probably don’t care whether or not you were expecting it, but they do care whether it will fix itself or requires intervention.

3. Intended to be funny: Well, this is embarrassing

The example is from Firefox being unable to open a page, but Chrome’s “He’s dead, Jim”, or the Twitter whale, are more of the same, and the trend has been spreading, perhaps due to advice like this post from UXmas: The 4 H’s of Writing Error Messages, where “humorous” is one of the H’s, as the author claims it helps diffuse frustration. I disagree–and actually even the UXmas author himself goes on to warn that humor is not appropriate in most actual error situations.

Cutesy, chummy, intended-to-be-funny error messages may serve that purpose the first time the users see them. But error situations have a way of repeating themselves. The tenth time you get to the same error, the funny, “friendly”, conversational error message style is likely to have grown on you much like a fungus. There’s a reason there are tutorials for Getting Rid Of Firefox’s “Well, This Is Embarrassing” Message.

Being helpful is about being respectful to the user. Error messages should be troubleshooting assistants for users, not their pals. An actual pal might buy the user a drink when the operation fails for the 15th time, the error message will still just say the same thing.

Helpful error messages are hard (to write)

Users are annoyed when something fails. We don’t want to feel like we did something wrong, or like we spent our time, money, or both on a product or service that isn’t up to the job.

Writing helpful error messages is hard, but probably one of the best possible uses of a technical communicator’s time.

Which error messages are most annoying to you? Do you enjoy the use of humor?

Categories
Software Development Technical Communications Usability

Helpful Error Messages For Fun And Profit

Grafitti: Support grows for the war on error

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)

Categories
Technical Communications Writing

Kill Your Darling Tech Analogies (Almost Nothing In Life Is Like A Car)

Old car matching a building in Grünerløkka, Oslo.

Over the years, I have come to fear and loathe most uses of metaphor, simile, and analogy in technology discourse. Interesting, helpful analogies are the exception rather than the norm.

What makes a bad analogy?

The main problems as I see it, are that the images people use tend to be:

  • Unoriginal and predictable. 9 times out of 10, it involves a car or traffic. (Seriously, have you tried a Google search for * is like a car?)
  • Hard to understand. How many people understand, in technical detail, how a car works?
  • Far-fetched at best, faltering and completely unnecessary at worst. Because not that many things in life are like a car.

Explaining an unknown with an unknown

Far-fetched is your smallest problem if you are able to get the first two right; be at least somewhat original and make it understandable to your audience.

Understanding is where you can’t afford to fall short, because for an analogy to be successful, at least one side needs to be well known to your audience, and both of them need to be familiar to you. You can explain something your audience doesn’t know by comparing it to something they know. Or you can give them new perspectives on something they do know by comparing it to something that might be new to them.

However, way way way too often, I see tech analogies that try to explain an unknown with an unknown. An audience that is already struggling to grasp a technology concept, is asked to wrap their brains around another concept that is somehow related to the first, in ways that shall only be fully revealed once they properly understand both concepts.

I’m not going to claim that it is impossible to pull such a dual explanation off. But it is very hard and requires the speaker or writer to realize that they must explain both sides of their analogy for it to work.

Ignoring cultural context is a related pitfall. For example, some traffic rules vary by country and continent, as do knowledge of and interest in sports. On this subject, I recommend Espen Andersen’s blog post on Pitfalls for the US speaker in Scandinavia.

Loving your analogies too much

The real problem with doing away with poor metaphors and analogies, though, is that as their makers, we tend to fall in love with them. I don’t use them a lot myself, but when I do, I can find myself struggling to make connections where few exist even as I realize it adds little value. William Faulkner adviced that writers kill their darlings. Analogies should be near the top of the hit list. Refusing to see past an analogy’s shortcomings can only hurt your case. Bad analogies are likely to leave your readership confused, annoyed, zoned out–or led down a ridiculous line of argument by a faulty analogy that devolved into a discussion on traffic rules when the subject at hand was copyright.

Analogies are the darlings of many a geek with something to convey, but there is little to indicate that the receiving end yearns for more analogies. In my experience as a tech writer, I don’t think I have ever seen a request for comparing technology to other things when users are struggling to understand something. One of the most common requests, on the other hand, is more and better examples.

Killing poor analogies in three steps

If you want to avoid unhelpful analogies, this is my advice:

  1. Don’t use a car or traffic analogy, unless traffic and cars are part of the subject matter at hand. There might be a fantastic car metaphor for what you’re about to explain, but if so, it has in all likelihood been done to death already.
  2. Pick an analogy where at least one side will make sense to the audience, and where both sides make good sense to you. Go with something you know well and can talk or write about in a compelling manner. Don’t try to explain Transport Layer Security by comparing it to a kevlar suit if you have a limited understanding of either. Competent audience members will see straight through it, and your analogy will have weaknesses that you can’t even know about.
  3. Test your analogy on as many friends or family members as you can dig up, trying to make sure they have a somewhat different skillset than your own. Ask for their honest assessment of your analogy: is it interesting? Do they understand it? Is it helpful?
    • If yes, you have an analogy that seems to work well. Now try to avoid overselling it. “With ready-made WordPress themes, giving your blog a makeover is as easy as dressing up a paper doll” is a reasonable simile, while “WordPress blogs are paper dolls” is taking it too far, in my book.
    • If no, kill it, and skip using an analogy altogether. A straightforward explanation accompanied by one or more relevant examples will be every bit as helpful as an analogy. Probably more.