Error Messages for Enterprise Mobile Applications — part one

First in a short series about how to write end user error messages for enterprise mobile applications.

For over thirty years I have been developing software - a lot of it for the enterprise and a lot of it mobile. I have encountered many many errors in that time. The easiest to fix were those that had good error messages. This series of posts will give you some guidance on how to write good error messages for your end users.

If you read this far, it seems likely that you care about error messages. But do you care enough to spend thirty minutes writing one? You should.

Your time is cheap

When you have to write an end user error message, you might be tempted to rush. The horned programmer on your shoulder tells you to write whatever quickly and then get back to some coding. If you don’t resist, you might write something like this:

Inactivity tracking detected days more than the 60 administrator configured max inactive days

A bad error message is a software problem. This means that its cost can be assessed by applying the general rule of quality assurance, as follows.

The closer a problem is to the customer when it is found, the more the problem will cost you.

The cost assessment works like this. A bad error message in production first costs customer time. Then it creates a chain that costs administration time, then first-line support, second-line support, maybe the account team, and so on until it gets to the programmers. They look in the code to find out what the error message means. Then the interpretation goes back down the chain, again costing everybody time.

Writing a good error message in development only costs programmer time. The same is true of fixing bad error messages in development. Good error messages aren’t quick to write, but they’re worth the trouble. Spending a bit more programmer time saves a lot more of everybody else’s time.

Ironically, the more time you spend on an error message, the shorter it could be.

Hardboiled

Write brief error messages. The mobile screen is small. The end user is busy. Your message will be read in a situation that is full of distractions.

A long error message might work on the big screen at your desk. A brief error message works even on the damaged and dirty screen of a three-year old mobile device that is being read by an end user who is crossing the road.

You can’t beat TL;DR. Don’t write like Dickens. Write like Jim Thompson or Elmore Leonard: hardboiled.

Some common advice to writers is to stick to what you know. That advice goes for error message writers too.

Lifeline

Only put information that is known to be true in an error message. The real cause of an error won’t be known and the user will be mired in uncertainty. Guesses and assumptions won’t help them.

For example, suppose the error is that the user’s passcode wasn’t recognised. The cause could be any of the following.

• They typed it wrong.
• The authentication service is down.
• Part of the network infrastructure that should connect the application to the authentication service is overloaded.
• A different user account has been selected.
• The end user’s domain membership has been changed by mistake.

There are things known, and things unknown, and in between is an error message. Don’t hold up a mirror of confusion. Throw the user a lifeline by which they can be dragged out of the mire.

Ensuring that a message contains only information that is true may require some nuance, and therefore more words. The text could then go beyond what fits in a brief message.

Detail Second

Include nuance and detail in a secondary error message. The secondary message doesn’t have to be presented in the same way as the main error. Facilitate the user to do one or more of the following, for example.

• Copy the message to the clipboard, so that the user can paste it into a note or mobile document.
• Open an email editor with the error message pre-populated into the body, or into an attachment.

The end user might understand the details in the secondary message. If they don’t, they will know somebody who does, or they can search the internet, or search a knowledge base. Give them a fighting chance. Any details that can’t be accessed by the end user certainly can’t be understood, nor can they be shared onward.

Summary of part one

You can write good error messages. Start with this guidance:

• Take your time writing - your time is cheap.
• Write like Jim Thompson, hardboiled.
• Throw the user a lifeline of truth.
• Let the user get the details.

Part two will have more guidance. Improvements will be made to this error message:

Inactivity tracking detected days more than the 60 administrator configured max inactive days

Look out for it soon.

Cheers, Jim.