Error messages, explained without the jargon

We end up explaining this on discovery calls often enough that it deserved writing down. Here is error messages without the vocabulary that usually surrounds it.

The measurable part of design is whether people can find what they came for and act on it without hesitating. Anything you cannot measure here, you are deciding by taste, which is fine as long as everyone knows it.

The short version

Say what went wrong and what to do about it. This is the sort of thing that compounds, quietly, in both directions. It is the sort of thing that looks like polish right up until it costs you an enquiry.

Why people complicate it

Most of the confusion comes from tooling rather than from the idea itself. That sounds obvious written down. It is still the thing most often skipped.

Never blame the person reading the message. In practice this is a scheduling problem more than a technical one. Most teams find the first pass takes an afternoon and the maintenance takes minutes a month.

Making it stick

Put the error next to the field that caused it. The teams that handle this well are rarely the ones with the biggest budgets. Assume whoever inherits this will have half your context and none of your patience.

How to tell if yours is fine

Design decisions are the ones clients feel most confident arguing about, which makes it worth separating taste from evidence early. Three things worth confirming about error messages before you move on:

• Someone can say what the current setup is without going to look
• Never blame the person reading the message — and you know whether that is true here
• There is a way to tell whether the last change to this helped

If you are not sure where your systems currently stand on this, it takes us about an hour to find out.