Clueless Error Messages: Clarifying

Try to remember what original and unusual error messages you were given by numerous programs and applications that you use. Surely each of you will find a couple of funny examples of such messages. In my personal rating at the moment, the undisputed leader is “The method returned something wrong“. If there is a scale of informativity of messages, then the given example on this scale tends to zero.

Here, the system is essentially telling us that an error has occurred. We will not receive any more information from this text. Unless we find out that somewhere in the depths of the system itself there is some method that returned something wrong. The value of this knowledge for the average user is zero.

It can be assumed that this text is an artifact left over from the process of testing the next functionality. Some flag left by the developer at the alpha testing stage. For the programmer, it clearly made some sense, but for the user it is completely useless.

Unfortunately, such messages in our programs and systems are not uncommon. Developers leave technical messages in the code, and sometimes they are simply too lazy to write a good informative error description. But such a text would not only help the user in their work, but would also reduce the number of calls to the support service. If the user is clearly explained what he did wrong and how to do it right, then he will surely cope with the problem on his own.

What should be the ideal error message?

Error message on the calculator Elektronika MK 52 / Wikimedia Commons
Error message on the calculator Elektronika MK 52 / Wikimedia Commons

5 basic rules

Susan Weinshank’s book The 100 Essential Design Principles provides the basic rules for writing an informative and useful error message:

  1. Tell the user what he did.

  2. Explain the problem.

  3. Explain how to fix the error.

  4. Use active rather than passive voice.

  5. Give an example.

The book has an example of how not to write error messages:

#402: before the invoice can be paid, the due date must be later than the date the invoice was created.

After the “Method returned something wrong” option, even such a message can seem quite informative. However, it has room for improvement. But first, as an experiment, let’s try to make it worse – let’s figure out how not to write error messages.

“Would you like to report a bug in the application to the developers?”
Ok
“Well, sneak!”
bash.im

We are no strangers – we have many years of experience in dealing with various products of the domestic software industry. Let’s get specific:

The invoice cannot be paid. Incorrect data entered.

To confuse the user even more, let’s hide the cause of the error from him:

The invoice cannot be paid.

Now let’s get close to our almost zero version:

Error executing the bill_payment method.

Further, to achieve the anti-ideal, we just have to remove the name of the method and creatively transform the text:

Unknown error.

I wonder if you got a sense of déjà vu when you read the examples in this subsection?

Error message when trying to open Microsoft Office / microsoft.com
Error message when trying to open Microsoft Office / microsoft.com

Adding information

In the event of a critical update error:
1. Determine the cause of the error.
2. Eliminate the cause of the error.
Microsoft Documentation

Now let’s move in the other direction on our scale – we will gradually improve the text of the message, guided by the rules of Susan Weinshank.

Let me remind you of the original version of the message from the book:

#402: before the invoice can be paid, the due date must be later than the date the invoice was created.

First, let’s transform the source text to make it easier to read:

#402: To pay an invoice, the due date must be later than the date the invoice was created.

Now tell the user what he did wrong:

#402: You entered the wrong payment date – it is earlier than the invoice creation date. To pay an invoice, the due date must be later than the invoice creation date.

Let’s highlight the essence of the problem in a separate sentence and clearly explain to the user what he must do to solve it.

#402: Failed to pay invoice. You entered the wrong payment date – it is earlier than the invoice creation date. Change the due date so that it is later than the invoice creation date.

Finally, let’s take a concrete example. In this case, we know the dates and we can use them in the text:

#402: Failed to pay invoice. You entered the wrong payment date 07/25/2021 – it is earlier than the invoice creation date 07/29/2021. Change the payment date so that it is later than the invoice creation date on 07/29/2021. For example, 07/30/2021.

We have significantly improved the error message – we took into account all the rules and almost approached the ideal. But let’s go up a level and see if we can make sure that the error does not occur at all.

Best Error Message

Method execution error: “Method completed without errors.”

There are phrases that you immediately want to write out on a yellow sticker and stick somewhere near the monitor. One such phrase is: “The best error message is no error message.” In other words, it is often easier to prevent the possibility of an error than to describe it.

In our example, no one prevents the developer from doing two things:

  1. When changing the date of the invoice, clear the field with the date of payment.

  2. In the interface, prohibit entering a payment date later than the specified invoice date.

These minor changes in the code will avoid the error altogether. And there will be no need to puzzle over the text of the message.

Unfortunately, such a simple way to solve the problem is not always possible. We cannot completely secure the application from errors. But it is in our power to make error messages more informative and useful.

The article was first published elsewhere on July 30, 2021.

Similar Posts

Leave a Reply