On Writing Better Error Messages
onlineornot.com
onlineornot.com
> Explicitly focus on "we" when the error is caused by an issue on your end
The “we” language tends to create a distance between the user and the software, emphasizing that the user is at the mercy of an anonymous “we” (who seem to be in numerical superiority, to boot) that are in control of the software instead of the user, who is implied to lack agency in comparison. This can make users feel patronized and pushed into a passive, dependent, and ultimately powerless role.
Microsoft is particularly egregious in this, in messages like “We’re setting a few things up for you”, implying the user is not supposed to be in control of what is being set up for them, like they’re a child, and not even deemed worthy to be informed about what specifically is being set up.
In an error message on the Internet, "You broke our server" vs "Our server doesn't know how to respond to your input, our bad" is not a power play, it's a bad error message.
Knowing who caused the issue helps the user figure out what to do next. 401/403? Better login/better annoy my boss for access. 5xx? Oh their server's broken, I'll try again later.
Imagine you are using a ticket machine at the train station, the machine happens to malfunction, and it displays “sorry, our ticket machine is broken”. That is just weird, because the user is only interacting with the ticket machine, not with people operating the machine. It’s not like you’re at the restaurant and the waiter is saying “sorry, our credit card terminal is broken” (which would be an appropriate situation to say something like that). Rather, the ticket machine should display something along the lines of “System malfunction, please retry after pressing the red button. Apologies for the inconvenience.” And similar in the case of a server software.
"404 I don't find your page"
"501 I'm broken"
The impersonal version waves any responsibility of the malfuction away. Was it the user? Was it the machine? Was it the machine's owner? Nobody knows.
With "our machine", there's a clear message sent about the accountability of the situation: there is someone owning the machine, and they failed to provide you service. Ideally, there would be contact information, so that the user has the ability to influence their surroundings.
A machine is not a law of nature, and should not be treated as such.
Heck, a law of nature which gets in the way - a fallen tree, a stray stone - can usually be fixed/moved/destroyed without fear about civil liability. A malfunctioning machine will ruin your day without you being able to do anything about it.
But I don’t want them to speak to me through the machine or tool. As already mentioned, it’s like they are self-inserting themselves into the interaction the user has with the tool. It makes the use of the tool less intimate for the user, because suddenly there’s a third party mediating that interaction. It can feel like intruding into the user’s privacy and autonomy. In the Microsoft/Windows case, it certainly often feels like that.
It’s bad enough for users when they don’t own the tool (as they would in case of a purchased local software) and only have temporary permission to use it, but they still like to think “this is my tool I’m using”, e.g. this is my Dropbox or my Google Sheet or my video game. A third party speaking through it however breaks that illusion, as it clearly brings the awareness of who’s really in control.
The other thing is that the user knows that it’s just a stock message, in which case any emotional expression put into it can feel disingenuous.
Your computer should be (although often isn't) doing things on your behalf, and only yours. There, the insertion would be jarring, and an encroachment.
I'm not quite sure where on that spectrum stand services which deliberately insert themselves between you and your data, like Dropbox or Google Sheets.
Stop blaming the user for mistyping when it's far more likely you accidentally changed a slug or dropped a redirect or deleted content in a migration or changed web server software without deeply verifying every link after that.
A client may think the URL is correct, but the URL's correctness is determined entirely by the server to which URL refers. Heck, that's why the server part of the URL is actually called "authority", for this exact reason.
Identifiers and the thing being identified are supposed to be permanently linked together. It's the webmaster's responsibility to pick an identifier they think they are able to maintain in perpetuity -- anything else goes against the expectations the web is built on (permalinks, bookmarks, writing down the URL on a post-it, etc.)
No, they are not. Where do people even get this ridiculous idea from? It sure as hell doesn't hold in practice at all, URLs (and the content thwey point to) change all the time for any number of reasons and yet I keep hearing this opinion professed over and over.
Links rot, that has been reality even before HTTP existed, and it will continue because Web is decentralized and you can't force your opinion on how it should be managed on everybody.
https://www.postgresql.org/docs/devel/error-style-guide.html
I wonder if it would be possible to incorporate such rules into my code editor's linter.
But the website doesn't know that... just because I got a 500 doesn't mean anyone knows or cares.
Just don't get too carried away here.
A few days ago when using one of the USCIS websites I came across a full stack trace including db table names and file paths.
As a developer, I am annoyed that we remove so much valuable info from exceptions. It would be better to include more info and then make it easier to dump this information into a logging tool, while the user gets a nice "d'oh" page.
Of course we would spend the time making better error messages within the product/service domain but that is time and money. Hence a trade off in the end.
I would categorize bad error messages as product bugs
An error message such as
Our service is down for maintenance
is infinitely better than:
Uh-oh! Something went wrong!Hell. No. "down for maintenance" implies some kind of maintenance is undergoing, which is often not true.
User would expect you are aware of the error, working on it. This can be false expectation.
It is definitely true, though, that the user can't do anything to fix it. They just have to try again later.
All this, of course, assumes that the code is returning proper error codes, which might also be a false assumption :)