Very well-written article with good examples and advice.
Write better error messages
91–100 of 265 posts
Re: Write better error messages
#92Earlier quoted context omitted.
This just means that the error message needs to be more clear. For example, after the error itself, it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to . Set ENVVAR to a proper value and restart the service.” Notice the direct language. It reads like an order. The less direct the message, the higher the chances that the user will not act upon it.
>it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to . Set ENVVAR to a proper value and restart the service.” Really, should logs also be documentation now ? Just mindlessly logging the same "advice" over and over again each time the error happen ?
If the error results in the program shutting down, it’s once per fatal interaction.
In other words, yes.
Re: Write better error messages
#93I 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:…
I've seen this constantly over the years, people who absolutely refuse to read the simplest instructions, but instead require step-by-step hand-holding from you personally.
I have no idea how these people get through life at all.
Re: Write better error messages
#94@Microsoft read this article! ;)
Re: Write better error messages
#95> 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.
I don't understand why they wouldn't have a dropdown below the error that would reveal the technical jargon.
Re: Write better error messages
#96Earlier quoted context omitted.
This just means that the error message needs to be more clear. For example, after the error itself, it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to . Set ENVVAR to a proper value and restart the service.” Notice the direct language. It reads like an order. The less direct the message, the higher the chances that the user will not act upon it.
The problem is people are not rational… and we try to solve that with software. Many people just lock up when software doesn’t do what they expect.
Lots of people find ways to irrationalize being rational.
Re: Write better error messages
#97I 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:…
I've seen this constantly over the years, people who absolutely refuse to read the simplest instructions, but instead require step-by-step hand-holding from you personally. I have no idea how these people get through life at all.
I suspect that, at least subconsciously, they're to some extent doing that to punish you for writing 'bad' software that they have to struggle with. If they're going to suffer, you're going to suffer right along side them.
Re: Write better error messages
#98I 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:…
Shouldn't the app gracefully exit with a clear message, and not bail out in a way that looks like a crash? I'd guess that the person who wrote it hooked into the error handler because that was the easy thing to do rather than bother to write a nice way to exit properly.
The fact that you've had this a dozen times points to a problem with the app more than the people using it to me.
Re: Write better error messages
#99I 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:…
Actually reading (and understanding, acting upon) error messages seems to be part of the learning process of every developer. And while more senior devs usually do read error messages, even they sometimes, rather than reading it will jump to behavior like "trying again a different way", before looking closely what went wrong.
Developers often seemed shocked that people can’t find the important error in a wall of text. A particular peeve is when the same error is reported three ways and the real error is sandwiched between others or scrolled off the screen due to spammy behavior.
Re: Write better error messages
#100Earlier quoted context omitted.
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.
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.