SoylentNews is people
SoylentNews
Submitted via IRC for TheMightyBuzzard
Try this simple technique to write messages that help users understand the reason for errors.
The first time a user encounters an application's documentation, it's not always with the user manual or online help. Often, that first encounter with documentation is an error message.
Technical writers should be involved in writing error messages. It's an important, although often overlooked, part of the job. After all, error messages are documentation, albeit documentation that's embedded in the code.
[...] An error message should be meaningful. By that, I mean full of meaning not only for a developer, but also for the user of the software. To prevent any panic or confusion, the message should be clear.
A meaningful error message should:
- be short (you can write in sentence fragments);
- contain a description, in plain language, of what went wrong; and
- use wording or a tone that doesn't (whether explicitly or not) blame the user.
Source: https://opensource.com/article/17/8/write-effective-error-messages
(Score: 1, Touché) by Anonymous Coward on Friday August 18 2017, @09:22AM (16 children)
Ah, the wonders of "This program has performed an illegal operation"...
Next problem: how get users to read error messages.
(Score: 3, Funny) by driverless on Friday August 18 2017, @09:51AM (1 child)
When an error occurs in my program, I've always found that lighting up a giant '?' in the middle of the dashboard is fine as an error message. The experienced user will usually know what's wrong.
(Score: 0) by Anonymous Coward on Friday August 18 2017, @09:58AM
Wherefore your moniker, then?
(Score: 4, Insightful) by DannyB on Friday August 18 2017, @03:31PM (8 children)
If you consistently provide error message which are helpful and useful, then users WILL read them.
Error messages should be actionable. Don't just say "syntax error". Say "missing comma after Aardvark".
Or better yet, if the program understands that to be the problem, then make it a warning, and try accepting it anyway, if the result would be unambiguous. Use backtracking parse or search to investigate all possible parsings with and without that missing comma after Aardvark. If the users input could have only one possible meaning, then accept it and make the red error a yellow warning instead. (But use words like ERROR and WARNING for users who can't see color.)
Next, another one of my favorites.
Exceptions.
If your (web based) application throws an exception, then in the exception handler, DO NOT display the raw exception to the end user. Rather, log it, with a short unambiguous code like U13AK. Say that an error has occurred, and if you call Tech Support, then BE SURE to mention the code U13AK.
Provide support people tools to look up the code U13AK and find the complete text of the exception that was thrown. That way the tech support people have the entire exception, but none of that info leaked to the end user.
Another thing. Write errors with a GOAL of the user NOT calling for tech support. Not only make the error actionable, but make it so that the user is not confused, and able to solve the problem without calling for help. Both for the poor user's sake, AND to reduce tech support costs. When the user has to call tech support, they're already having a bad day, and you're making it worse. If the call gets escalated to my level, then they're really having a bad day and I really try to make sure they are happy when we're done. Not just a lame "are you satisfied with the resolution of this call", but that they're really happy. I don't work in tech support, so I don't have such constraints, stupid scripts and platitudes if a problem gets to my level.
Now about that unambiguous code like U13AK. Use an alphabet which I call "base34". It is the 10 digits and 24 characters of the alphabet, excluding the letters "o" and "L", which resemble zero and one respectively. Print a base34 code with uppercase, but when an operator or user types it in, accept upper or lower case, and if O or L are typed, interpret them as zero and one. That makes things more pooch screw proof.
Hope that helps.
If you think a fertilized egg is a child but an immigrant child is not, please don't pretend your concerns are religious
(Score: 4, Informative) by bryan on Friday August 18 2017, @05:09PM (2 children)
I'm a fan of Crockford's base62 [crockford.com], which is very similar.
(Score: 2) by DannyB on Friday August 18 2017, @08:18PM
+1 Informative - Thanks
If you think a fertilized egg is a child but an immigrant child is not, please don't pretend your concerns are religious
(Score: 1, Funny) by Anonymous Coward on Saturday August 19 2017, @12:11AM
It's great that he left out 1, I, i, L, l, 0, O and o. However the "3" looks a lot like a "6".
(Score: 3, Informative) by frojack on Friday August 18 2017, @06:15PM (1 child)
This, a thousand times this!
If you can't be bothered to write a proper error message, then at least tag it with some sort of semi-unique code that researchers or end users can search on the web. Even the lazy programmer would eventually get help from crowd sourced on line error databases.
Just smack in a UUID with some prefix, and call it a day: KDE-Dolphin-ae04582a-ca27-4e81-9ffb-35aa18244a10 is a lot more useful than 15 occurrences in the code base that have the same "An error has occurred" text.
Goes for "actual software" as well as the crap agile web-app developers spewed out by lash-ups-Я-us programmers.
No, you are mistaken. I've always had this sig.
(Score: 2) by DannyB on Friday August 18 2017, @08:23PM
I'm not sure, but you seem to be suggesting tagging a certain error with a common error code. That is, many users might get a U13AK error.
I was thinking that each time the exception is thrown, a new code is generated, and logged with the exception. That way when a user calls with code U13AK, what you are researching is that specific occurrence of the exception. You can look up other occurrences of the same exception by the class and line number that threw the exception.
This might confuse users. But maybe generate both a common, and a unique error code. So all users who do this particular thing get an ID10T, but the one time it happened right now, the user got a U13AK along with it. It's like ID10T would be associated with the location in the code where the exception is thrown.
If you think a fertilized egg is a child but an immigrant child is not, please don't pretend your concerns are religious
(Score: 0) by Anonymous Coward on Friday August 18 2017, @06:57PM
The problem with syntax errors is that the actual reason for the error is usually not knowable because the program cannot divine the intentions of the user. All it can really do is look at the current parser state, which is probably completely bogus (the input is already known to be invalid, after all), and try to guess what the user actually meant by it. Computers are notoriously bad at this. Sometimes this works OK, other times it will be completely wrong.
The parser can explain which part of the input did not match its expectations, and perhaps even what those expectations were. Outside of trivial cases, this will likely require some knowledge of how the parser works for the user to comprehend it.
Some parsers attempt to re-synchronize after detecting an input error in an attempt to proceed anyway. Again, sometimes this works OK, other times this makes the situation even worse.
(Score: 0) by Anonymous Coward on Friday August 18 2017, @10:00PM
There should be a distinction between anticipated error messages and un-anticipated. For example, if you can detect the PC or application is out of memory, then you can tell the user that the application doesn't have enough computer memory to continue. However, if you go to allocate memory and the allocator API itself returns "unknown error" or the like, then you cannot give a clear description of the problem to the user. The programmer using the API cannot tell either (unless it happens under testing and experiments can be done). The best one can do is guess and suggest: "This application encountered an unanticipated problem while trying to request more computer memory. It's possible your computer's memory is full." Being caused by lack of memory is only a guess. An "unknown error" by a memory allocator could be caused by defective RAM, cosmic rays, defective bus, defective allocator logic (api bug), etc.
(Score: 2) by turgid on Sunday August 20 2017, @09:39PM
Exceptions are great fun. The whole point of exceptions is to spew out a stack trace at the unsuspecting luser when the "developer" can't be bothered to check the return codes from function calls in the right place. It's Enterprise(TM) and Professional(TM) and it makes your code look really cool when it dumps stack.
I refuse to engage in a battle of wits with an unarmed opponent [wikipedia.org].
(Score: 2) by bob_super on Friday August 18 2017, @05:20PM (3 children)
In a previous life as an FAE, I dealt with engineers using pretty specialized tools.
Way too many see the popup with the red cross and five lines of explanation, and close it without reading, before asking me to fix the problem. Many of our error messages were actually pretty detailed and would give you the answer. But the customers didn't realize the tools had progressed since the days of useless "some error occurred" messages.
But then, there were some clearly-ESL messages which had obviously never been reviewed by a native speaker. With enough experience, you can find out whether the coder was Indian or Chinese, because they don't make the same English mistakes.
(Score: 2) by frojack on Friday August 18 2017, @06:17PM (1 child)
Put it all on line, and get google sort it out.
But you need some unique-ish thing to search.
No, you are mistaken. I've always had this sig.
(Score: 2) by bob_super on Friday August 18 2017, @06:22PM
Unique error codes, which you can google with the tool name, are pretty good, if someone already had the same problem.
I tried to lobby to release a database of error codes (where it comes from, why, what to do), but when the tool is over 10GB (now 30) with over 100k files, it's too late to start...
(Score: 2) by maxwell demon on Friday August 18 2017, @08:04PM
Maybe if the user clicks OK too quickly to have possibly read the error message, pop up another box with a short quiz about what the error message they just clicked away actually said. :-)
The Tao of math: The numbers you can count are not the real numbers.
(Score: 1, Interesting) by Anonymous Coward on Friday August 18 2017, @07:32PM
I actually solved this problem with my users by making up error codes that sound technical. I borrow from the style of actual C library error codes, and sometimes I use error codes straight out of C like ENOENT. Make sure it starts with the letter E, is all caps, and is cryptically just enough like something that could be one or two English words.
They remember it every single time. The first time I did that was out of sheer frustration. Then, to my complete and utter surprise, users started mentioning this specific EFIZBAZ error code, telling me exactly where the problem was. It was bliss! Except for the fact that without reading TFA, I'm going to bet the author is going to say that what I found is unpossible.
Give the user a short, clear, concise explanation of what went wrong. The user will never fucking even try to read it!
Give the user EBINWIDGET. They report it correctly every single fucking time! And I must have 50 different, completely made up error codes like that running around by now!