They recommend, avoid technical jargon so change it to:
'due to a technical issue on our end'
but isn't that also generic and obvious which they were trying to avoid too.
Write better error messages
181–190 of 265 posts
Re: Write better error messages
#182> 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 think the point they are making here is that clearly stating what went wrong doesn't necessitate using "technical jargon". Now, "your credentials have been denied" seems pretty clear and does not use jargon in my opinion, but telling the user "the ajax request failed, returning a 403 http error code" seems unhelpful and doesn't tell them what happened.
Even in your example there's a world of difference. "Your credentials have been denied" implies a problem with credentials, while 403 clearly states that the credentials are valid, they are just denied access to this resource.
I know it is a made up example, but it does show the problem with "dumbing down" the error messages. Details matter.
Re: Write better error messages
#183"Passing the Blame" in particular is a personal pet peeve. I hate when apps phrase errors like I did something wrong by clicking the totally normal link. Closely related is the general trend of "lol wut" tone in error messages, which really grates when you're frustrated and doing something that might be very important. "Whoops! We made an Oopsies! Sorry :("
Re: Write better error messages
#184If you're raising an exception deep in some internal code, provide as much detail as possible. If the error bubbles up to the user, then either the information is over their head, in which case there's no difference to a non-detailed error message, or the user/support person can actually act on it. The most infuriating error I see is "file not found"... WHICH FILE?! Of course if the error is found in the higher level…
> If you're raising an exception deep in some internal code, provide as much detail as possible. > If the error bubbles up to the user, ...then you have an information disclosure vulnerability! There's a really good reason why we don't bubble up deep exceptions to end users: Attackers can use that info to gain information about your back end that they can use to find worse vulnerabilities. Put all the detail you want…
Yeah things are a bit different with web apps. There users usually can't do anything with the info even if they had details, so internal logs is clearly the place. But my point still stands: you want detailed info in those logs, not just a lone "file not found" without anything else.
Re: Write better error messages
#185I saw an error message the other day:
“Deployment failed because: deployment succeeded”
Re: Write better error messages
#18620 years ago I was working on Acrobat at Adobe. I was mostly the "Windows guy" but also worked and tested on the Mac.
When I tried to install Acrobat on my Mac, I got this message:
"Your hard disk is too small"
My what is too small?!
Later, on Windows I got this unexpected popup:
"You are not here"
WTF?
I searched the code for that string and found it in a function named "CantHappen()". This function was called in numerous places where the programmer thought there was no possible way for the code to get to that place. But of course CantHappen() did happen.
As I looked through the code I found many other messages that were bizarre and incomprehensible and sometimes downright offensive.
So I started a project to go through all our messages and make them more clear and informative - and even better, when possible to not have the message at all but just take care of the situation.
The underlying cause of these bad messages was twofold:
1. Programmers never got raises for writing great error messages or finding ways to avoid them in the first place. We were just rated on how much work we got done.
2. We did have a product designer who was supposed to specify all user-facing messages. But the designer mainly considered the "happy path" and didn't think about edge cases. It was left to developers working under time pressure to handle those.
Re: Write better error messages
#187This quote form a textbook in my graduate studies helped me a lot: “Error messages should be how to fix it messages.”
Re: Write better error messages
#188At 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…
This seems to be the approach that Android takes. If you try to connect to a WiFi network and it fails, it just gives up. It won't tell you why it failed. This makes it very frustrating to figure out what's wrong. Maybe I wouldn't understand the error message, but at least it would provide a starting place for me to look up more information or ask for help from someone knowledgable.
Re: Write better error messages
#189I 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 have managed to get a lot of notoriety in my company by just: 1. Paying attention to error messages 2. Reading documentation 3. Looking up stuff I don't fully understand(including googling error messages) That's it. Some people don't even read error messages at all. I understand non technical people doing that, but I've seen far too many engineers doing it. If anything doesn't go exactly as expected, they freeze. I…
> I'll move mountains to help someone that comes to me after having done some basic homework to try to fix (or at least triage) an issue. It very rare though.
These are rare, but they also tend to be the really effective ones. We have a couple of teams who understand the stack, read documentation and read error messages. We generally don't hear of them for months and months, because they are too busy being productive.
But when we hear of them, it's usually time to push boundaries of the infrastructure and the processes. They tried everything and nothing worked and now it's time to make it work.
Re: Write better error messages
#190I 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.
Hey, let's jump on a quick call, so we can go through this together and maybe update docs if they're out of date?