Error messages: Moving beyond WTF

on Jun 10, 10 • by Patti Murphy • with 3 Comments

By the time users hit the help documentation, they’re already snarly. Yeah, some people read the documentation first before using the tool, but… A lot of people just want to dive in and start using the tool. And when I’m stuck I want answers. Now, already!  You might think it’s stupid-user error and I...

Home » General Coding » Error messages: Moving beyond WTF

By the time users hit the help documentation, they’re already snarly. Yeah, some people read the documentation first before using the tool, but…

A lot of people just want to dive in and start using the tool. And when I’m stuck I want answers. Now, already!  You might think it’s stupid-user error and I might think it’s stupid software design, but who cares? I want help right NOW.

Troubleshooting information lives or dies by the search-and-I-better-frickin-find-what-I’m-looking-for mentality. How do we look for this help? We copy and paste error messages into a browser and search.

When my ideas about organizing  troubleshooting information compete with how Google finds stuff, Search Engine Optimization (SEO) carries the day.  Or at least it should. Of course, there are SEO factors that put help documentation at a disadvantage, but that’s another topic for another day and I’ll let Tom Johnson do the talking on that one.

What does this mean for me, a technical writer?

Well, if two (or 5) of our tools throw the same error message, I’m going to have one page for each error message and have instructions on that page that explain how to fix it in each tool. Yeah, it’s nice to have tool-specific help information, but Google gives more weight to page titles and URLs. For good measure, I’m going to repeat the error message in the body of the page and format it in bold or italics.

Sarah Maddox highlights elements of what makes a good error message (including some hilarious examples of bad ones), so no need for repetition.

Aside from clarity, what do I want in an error message?

Firstly, I’d like to be able to copy and paste it.

Secondly, I’d like the solution to be stated.

As an added bonus, I’d like to be provided with a link in that message that would bring me to the dialog where I can take remedial action. Then, I won’t even have to look for help information. I can just fix it. Here’s an example of one these helpful messages from our Eclipse plug-in:


See? Documentation not required. The solution is outlined, and you can click the link to get to the license dialog, where you can check your host and port information.

Hmmm. Maybe that would put me out of a job. Sergey, please change that message to:

ERROR:FROZEN:BAD LICENSE.

I have a mortgage to pay here.

Related Posts

3 Responses to Error messages: Moving beyond WTF

  1. Bill Albing says:

    I like your two essentials — being able to copy & paste the information, and providing a solution. But don’t pass too quickly over the other aspect — that the error itself should be clearly stated. Sometimes there are multiple causes and multiple solutions possible so unless you state what the error is clearly, you are holding back information from the user. I link to the solution or a link to more information is a great idea.
    Don’t worry about the mortgage; there is plenty of quickly developed (and error-prone) code to go around for all of us to stay employed.

    • Patti Murphy says:

      Good points, Bill. There are situations where there are multiple causes and a well-stated explanation is very useful too.

      It’s also a relief to keep in mind the sustained demand for our skill set. :-)

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to top