Setting the scene

You’ve got a great new feature – you’ve spent days and months testing and producing it and it’s ready. You’re ready to deploy, turn on the feature switch and GO GO GO. You know people are going to love it – and you’ve thought of all the possible issues that could arise.

But disaster strikes – you’re throwing exceptions and things don’t seem to be working the same as you found in your testing – what’s different you ask? Could it be the users? Could it be a different configuration? Or could it be your code?

Now nine times out of ten it’s not the user, it’s you! They are happily typing or clicking when bang, they get an error. Now, if you’ve done your job right these errors should be gracefully handled, the user should be told what is wrong and receive a reasonably helpful error message. But this is not always the case. So in this article I’m going to explore what I think makes a useful error and what you should do when things go wrong.

What is a Useful Error?

Over the summer I’ve been working on some cool projects (Expenses Uploads and Practice Transfers) that require a high degree of user input. Sometimes through misunderstanding or no fault of their own users encounter error. Especially within our Expenses and Mileage upload project we decided that we needed to provide “useful” errors to users to help them and our support teams diagnose and fix issues with their uploads.

This is when we need to come to a decision about what makes an error “useful”. I thought to myself: what are the key things I need to think of when providing an error? So I came up with 3 key criteria – specificity, usefulness and actionability. I would add that these criteria are not exhaustive and you may disagree with them but they are what I think makes a good error message.

Specificity

What is specificity? Well, we want our error messages to tell the user precisely where the issue is. Is it a general issue with a file uploaded, is it an issue with a line in the file or an email address entered? The user needs to know – if they don’t they can’t be expected to guess and fix it!

For us, this meant highlighting from which line in a file issues have arisen, giving the user the context of where the issue has happened. Or highlighting the specific field in which the user has mistyped an input – so they can see exactly where the issue is. We just need to tell them where to look to fix the issue.

Usefulness

If an error is not useful, what is its purpose? Sufficient details and information should be provided to the user at the time without overwhelming them with information. They should have enough detail to know what has gone wrong in a way that guides them towards the correct input.

Within the projects that I’ve been working on I really thought about this quite hard – we always, where possible, want the errors we produce to be useful. Sometimes this is difficult, as we’re showing the same error for multiple failure conditions and therefore have had to make a call about what is the best error to show. At other times it’s a process of translating from our technical speak to something that is more user friendly. For me this is when it is great to have someone else, like a product manager, to be able to ask what they think is best and guide what would be useful for users.

Actionability

All errors – apart from the very exceptional – should have some way for the user to continue forward and get themselves back on track! We should always give the user the opportunity to know what they are able to do – be it giving a list of input or linking to a help article.

Sometimes this can be the hardest thing to do: provide some action for the user to carry out in response to the error. We worked hard as a team to be able to provide users with lists of valid and accepted input, and to let them know if they cannot continue down the path they have set down and provided them with Knowledge Base links to help. I would argue this is the most important part of an error message as it provides the user with something to do and gives them the help they need!

So what should you do When Things Go Wrong?

In an ideal world we would be able to consider all potential errors and be prepared to deal with them, but sometimes you’ve not considered a case or thought that something like that could happen. This may cause unexpected funkiness and may end up making your feature work in unexpected ways.

This happened to me – and it can happen to you too! So what should you do? In my mind having some error is better than no error. If you can’t provide the full 3 key criteria that I’ve discussed but you can provide something – for example “there has been an unexpected error and our engineers are looking into it” – it is much, much better than nothing. If you don’t give any feedback when something goes wrong, users may get the wrong idea and think that what they were trying to do has succeeded even when it has not!

Conclusion

Errors are part and parcel of software development, and making them useful to users can be difficult. I’ve discussed 3 key areas that I think are important to think about when creating error messages – specificity, usefulness, and actionability. But at the end of the day – if something goes wrong just return an error. Your users will thank you for it!