Part Three: The details · Asking and deciding
An error is clear to the person who wrote the code. To the person reading it, "something went wrong" says nothing about what to do.
Error messages are written at the worst possible time. A developer is finishing a feature, hits a case that should never happen, and types a few words so the code can move on. "Invalid input." "Request failed." "Error 4012." To the developer these are precise. They know which line produced them.
The person who meets the message knows none of that. They were listing a product for sale, and it stopped. They need three things. What happened, in their terms. Whether their work is safe. What to do now. "Something went wrong" answers none of them. "Please try again later" is worse, because it gives an instruction with no reason to believe it will work.
Tone matters too. "Invalid" and "illegal" blame the person for what is usually the product's rule. A message that sounds like an accusation makes people defensive, and a defensive customer writes a different kind of support email.
Makers pull the other way. They fear exposing technical detail, or admitting fault. But vagueness does not hide the failure. It hides the way out. When the product truly does not know what happened, it can still say so, say that nothing was lost, and offer a person to talk to.
A seller uploads a 30 MB photo to an online shop that accepts 10. One version says "Upload failed." The other says the photo is too big, what the limit is, that the listing is saved, and offers to shrink it.
Upload failed. Error 4012.
OKThis photo is too large to upload.
It is 30 MB and the limit is 10 MB. Your listing is saved without it.
Shrink and upload Choose anotherTherefore:
Write every error for the person who will read it. Say what happened in their words, whether their work is safe, and what to do next, beside the thing it is about.
In practice. Search the codebase for every message a customer can see. Put them in one document and read them as a stranger would. Rewrite the ten that appear most often first.
Goes with. The best error is one that cannot happen: PREVENT THE MISTAKE (76). The ones people meet every day are where to FIX WHAT'S THERE FIRST (25), and when a message cannot solve it, offer A HUMAN WHEN IT MATTERS (52).