17/08/2014
For a time now, I have been trying to come up with a framework that allowed to me write good error messages. Since it took me some time to come up with a good framework, I’m sharing it and hoping it might save you some work.
When you are starting a project, it might not make much sense to overthink stuff like error and warning messages. But as your project starts to grow you’ll notice that error messages are hard to get right the first time you write them.
Another important aspect is keeping the messages consistent. Otherwise your product will sound like that bipolar girlfriend you had back in college. Sometimes she kissed you and then unexpectedly kicked you in the nuts.
Having a framework allows me to iterate on it, and understand what works and what doesn't. If I follow the framework and end up with an error message that users can’t figure out, then I can iterate on the framework and ensure the next messages will come of better.
Also, if I distill my knowledge into a framework, I can share it with the rest of my team, or even the development team. This way, we will all start writing in a consistent way, which has a positive impact on the quality of the platform.
A good error message has three parts:
If you are writing or reviewing your error message, first focus on getting these three points written. Even if the message is awfully long, don’t worry about that when first writing. You can always go back and simplify it later.
But the opposite is not true. It’s difficult to shape a small message into one that clearly explains the problem, cause, and solution to the problem. You will be constantly editing your thoughts to ensure the message stays small, and at some point you will become blocked. Yes, I've experienced that problem several times, so I know how hard it feels.
After you ensure your message contains all these three parts, its time to review it. You need to edit it to ensure it:
As you can see, this framework is simple and does not need much thought. If you are only interested in the framework, you can stop here. No seriously, go use it, and let me know how it goes.
If you want to learn how I’ve come up with it, or you want to see other interesting resources, feel free to read ahead.
The other day I was reviewing some error and warning messages that used in the OutSystems Platform. When I finished I wondered how could I be sure that those messages were really helpful?
I had some practice writing and reviewing error messages. Nonetheless, some of the errors were quite tricky to troubleshoot. How could I be sure that when a developer encountered that message, she would immediately be able to fix the problem?
For starters, I could (and often do) user test it. There’s no need to waste time setting up a fancy way to test the message. Just print 5 or 10 error messages, and test them with someone from your target audience. If they look puzzled, you know what you’ve got to do. If you can’t easily test with someone from your target audience, test it on your colleagues. Someone from your team, someone from sales, marketing, or even the receptionist. They might be biased, but few feedback is better than none.
User testing a message doesn't consume much time. Yet, it would be useful to have some framework that could help streamline the process of writing error messages. This way, obvious mistakes would jump to our attention. We wouldn't need user tests to figure out obvious mistakes.
Also, at OutSystems we have a couple of things that play in our favor:
Nonetheless, I was searching for a small, no-BS framework. My secret goal was to hand those couple of rules to the development teams. That way they could write nice error messages and the quality and consistency of the product would improve. And yes, I would sleep better knowing that when someone adds a new error message, it will be easy for end-users to understand what it means.
I had read the Microsoft Manual of Style a while ago, so I didn’t remember if it had a chapter about error and warning messages. The fact that the Microsoft Manual of Style is more than 450 is a double edge sword. It covers several topics in a deep way, but it's difficult to remember everything in it.
So I had no other option than to read it a second time. I (re)learned that it has a chapter dedicated to grammatical elements, and another to punctuation. Unfortunately, no chapter of framework on how to write clear and understandable error messages.
Although there was nothing on the Microsoft Manual of Style, I was sure that Microsoft had a few guidelines on how to write error messages. Despise what most people think, Microsoft goes to great lengths to ensure their users have a consistent experience throughout their platform.
So I kept searching, and found out they really have some guidelines, but they are dispersed all over msdn.
Fortunately, my patience paid off. Buried among this guideline, are three small rules that make a fantastic framework. The style guide states that an error message must have:
In my research, I found several other style guides. Some were better, others were worse. One that is worth mentioning, is Apple style guide. Just like Microsoft, they seem to have several style guides dispersed though the web. They also seem to focus a lot on the correct usage of grammatical elements and punctuation. However, they don’t seem to have a structured framework for writing error messages.
This post by Jakob Nielsen, also deserves to be mentioned. It contains a few guidelines about error messages. Nielsen highlights that an error message should be:
It’s no surprise that he has developed such a guideline. If you remember, one of his usability heuristics is “The system should help users recognise, diagnose and recover from errors”.
I hope this framework serves you well. If you think that something could be added, or removed to this framework, please reach out to me.