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: 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].