Nicely written piece with clear examples. It would be great to know the impact of this work. Perhaps one metric to look at would be the number of tickets submitted to customer care?
Write better error messages
111–120 of 265 posts
Re: Write better error messages
#112I would, if i had any evidence at all that they would be read and acted on. I’m convinced even seemingly competent people are just rendered contextually blind by the appearance of any error at all. In the past month, i’ve had about a dozen interactions like this: developer: your service crashed, here’s a screenshot of the last 5 lines of the crash me: do you see where the final text you just pasted is “RuntimeError:…
The problem is here: "RuntimeError:" . Once they saw that, they stopped reading. "Did not find ENVVAR" [..] "ensure this is set to the proper value" [..] "and then restart the service" are also obscure and will stop them from reading. Why is the user like this? Error message PTSD. Years of staring at obscure errors full of technical jargon that are not helpful to the user, has left them scared to even look at the con…
I tried exactly this approach! What I got was a bunch of developers copy-pasting the error message with helpful URL at me and demanding to know what they should do. The number who followed the link and fixed the problem themselves was shockingly small.
Going out on a limb, I think we're all going astray by trying to parse the error messages our fellow developers are reacting to. A great many seem to handle any unfamiliar or unexpected error message by giving up, no matter how friendly or informative or helpful it may be.
Re: Write better error messages
#113How about just engineering stuff to not have errors in the first place.
My toaster is a complex bit of engineering - it has thousands of parts which all work together to take power from the wall to make toast.
Yet it has no errors. It just does the job I ask it to do.
A computer on the other hand seems to have a lot of ways to fail, and does so nearly every day. I suspect everyone reading this comment has seen at least one error today. Can't we engineers make the software better so that these errors can't/don't happen?
Re: Write better error messages
#114At a previous job, writing unambiguous error messages was discouraged. Everything just had to be "Oops! Something went wrong"
The reasoning was that "users can't do anything with information we tell them anyways", despite the overwhelming number of help desk tickets we'd get from "Oops!" appearing in a million different scenarios with no clear way for us to tell what error actually caused the message to appear.
Users naturally report the messages that they see because they're helping us to see the problem. I didn't get why that was such a hard concept to understand
Re: Write better error messages
#115I really like this. There are clear shibboleths which identify the author as a person who deeply respects and cares for the readers of error messages, and their experiences. It makes me hopeful for the future of software when I see that there are others. Thanks for sharing.
Re: Write better error messages
#116At a previous job, writing unambiguous error messages was discouraged. Everything just had to be "Oops! Something went wrong" The reasoning was that "users can't do anything with information we tell them anyways", despite the overwhelming number of help desk tickets we'd get from "Oops!" appearing in a million different scenarios with no clear way for us to tell what error actually caused the message to appear. Users…
That seems like peak uselessness. Even "Error code 0x00ad4829" is a more useful message, because even if it's useless to the user it is useful to somebody.
Re: Write better error messages
#117At a previous job, writing unambiguous error messages was discouraged. Everything just had to be "Oops! Something went wrong" The reasoning was that "users can't do anything with information we tell them anyways", despite the overwhelming number of help desk tickets we'd get from "Oops!" appearing in a million different scenarios with no clear way for us to tell what error actually caused the message to appear. Users…
That seems like peak uselessness. Even "Error code 0x00ad4829" is a more useful message, because even if it's useless to the user it is useful to somebody .
There is some logic, the "you don't want to expose your internals". Really useful messages might contain a lot of details about the tech stack you use (giving a nice hint into which CVEs to try).
That said, this is an easily solved problem. The best solution is to aggressively log errors AND prioritize having dev teams push that error count to 0. If an error happens, it's a bug.
The next way to solve it is simply a report button. Let the users click a "I'm mad at you for not working" button and embed something like a session ID that allows internal queries into what went wrong.
Error codes are a terrible solution, but perhaps an OK option if this is not hosted software. That said, a more user friendly approach would be a QR code with all the relevant details embedded.
Re: Write better error messages
#118Earlier quoted context omitted.
The trick that I've found is that each error message needs to be unique... not just the stack trace, but the actual wording of the message leading up to that. Get a screenshot or the exact verbatim of it, and you can identify exactly where in the code it originated. User reports are unreliable, but when I can pinpoint where the message originated from, it massively cuts down on the troubleshooting time.
In RFC 7807 all errors get an unique URI. Message texts might change or be translated into a language you don’t understand.
To be precise, each error type gets a unique URI.
A good way to take advantage of that is to have a central database of all error types, but not many companies bother to do that.
Re: Write better error messages
#119> Even in today’s world of user-centered design, technical jargon still sneaks its way into error messages. You couldn’t fetch my data? My credentials were denied? What? The technical stuff is not important to the user This is the opposite of what I want. Stop condescending and just tell me what actually went wrong.
How many times I had to strace an application because the fucking error message didn't give enough information!!
Re: Write better error messages
#120I would, if i had any evidence at all that they would be read and acted on. I’m convinced even seemingly competent people are just rendered contextually blind by the appearance of any error at all. In the past month, i’ve had about a dozen interactions like this: developer: your service crashed, here’s a screenshot of the last 5 lines of the crash me: do you see where the final text you just pasted is “RuntimeError:…
The goal of writing better error messages isn't to help the people who never read error messages, it's to help the people who do and who you never have to hear from.
I am reminded of the classic non-intuitive survivorship bias example from WWII re: armoring bombers: https://en.wikipedia.org/wiki/Survivorship_bias#In_the_milit...