Tell me something I don't know

A helicopter was flying over Seattle when an electrical short disabled all of its navigation and communications equipment. Due to the clouds and haze, the pilot could not determine the helicopter's position and course to fly to the airport.

The pilot saw a tall building, flew toward it, circled, drew a handwritten sign, and held it in the helicopter's window. In large letter, the pilot's sign read: "Where Am I?"

The people in the building quickly drew a large sign, and held it in the building's window. Their sign read: "You Are In a Helicopter."

The pilot smiled, waved, looked at his map, determined the course to SEATAC airport, and landed safely.

After they were on the ground, the co-pilot asked the pilot how he determined their position.

The pilot said, "I knew that had to be the Microsoft building, because they gave me a technically correct, but completely useless answer."

Come again?

Yeah, this is an old joke that's been circulating the Internet for years. But there's still a lot of truth to it.

While Microsoft is famous for writing incredibly useless error messages into its software products, it's not the only offender on this score. Just recently, I ran into these two beauties:

Windows error box

Mac OS error box

The first message, generated by Windows NT, just might be comprehensible to you if you know what a register is. But the second, generated by Mac OS, takes the prize for chasing its own tail. It didn't help that the dialogue box couldn't be dismissed, either.

In many high-tech companies, writing error messages is the job of the developer. After all, the person who writes the software probably understands error conditions in the program better than anyone else, right?

The problem with this approach is that programmers view their work from the inside out. Programmers see the guts of their products all day long, and so tend to suffer from a perspective problem. The error messages they write tend to describe incorrect numerical results, rather than procedural mistakes. But this is not what the customer needs to know. Who cares if the floppy disk controller has the wrong values in its registers? What you need to be told is that you should stick the floppy disk back in.

Programmers also tend to believe that the customer will never see the error messages. Once in the field, the product will work correctly, and will never, ever display a programming-level error. This, unfortunately, is wishful thinking.

Writers should write error messages

Technical writers should always be included in the creation of error messages. It is the best way to ensure that when something goes wrong, the customer will have at least some useful information at hand.

Granted, there are some programmers who can actually see the forest despite the trees, and write messages that make sense to the average person. But these programmers are like unicorns: rare, and seldom seen. You should institute a policy within your development team so that the technical writing staff reviews the application error messages during the beta cycle.

Once you have the error messages in hand, what do you do with them?

Error messages should always have two parts:

And if you're doing a really great job, the message might also include information on how to avoid the problem in the future.

The nitty-gritty

However, it is not always easy to provide this information. The biggest difficulty in making error messages comprehensible is that often the programming code generates a single message for multiple error conditions. Sometimes, the program can be made a little more intelligent, and split different errors apart. But sometimes not. So, it is often difficult to provide useful information.

For example: A networking router will generate a timeout error if the latency period on the network grows too large. But it might generate the same error if someone trips over a network cable, and yanks it from its socket on the router. In both cases, the router is unable to communicate with the network. How do you provide meaningful information in the error message?

This is a case where communication with the developer makes all the difference. Before you write (or rewrite) the error message, sit down with the developer, and get a description of all the possible situations that can cause the error (this can be a complex process). Group the error conditions by their context, if possible.

At this point, it might become clearer to the developer that the software can identify at least some unique error conditions, and generate unique error codes based upon the context in which they occur. If so, then your job is made easier.

If not, then you have some careful writing to do. Error dialogue boxes don't leave room for a lot of expository text, so you have to nail the most common problems in as few words as possible. But most importantly, you should not try to describe the error at length, but rather you should focus on what the customer can do to fix the situation.

In the router example above, the timeout error message might read: "Connection timed out. Check the physical cable for breaks. If cabling is okay, try increasing the value of parameter T23 to allow for high-latency networks. See the Reference Guide for more information on T23."

Eliminating error messages

There's one more thing that the developer and technical writer can do to make error messages less burdensome on the customer: Get rid of them.

Some of the time, error messages are not even necessary. Microsoft Windows is particularly offensive in displaying pointless error messages.

For example: You start to drag-and-drop a file in Windows Explorer, but then you change your mind, and return the file to its original location. Windows reports: "Error. A file cannot be copied onto itself."

What is the purpose of this message? It's not giving any useful information. It's not providing you with a copy/overwrite choice. It's just in your way.

A better method would be for Windows to simply ignore your aborted drag-and-drop action. There was no harm done, so why alert the user at all?

When you review your product's list of error messages, look for these situations, too. Sometimes the best way to deal with an error is to just ignore it.