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: 2) by mth on Friday August 18 2017, @09:23AM (7 children)
The problem with "Printing failed" as an error message isn't that it isn't clear, but that it's missing details: it doesn't say why the printing failed. Instead of trying to make wild guesses ("Is your printer turned on?") it would be far more useful to spend some development effort to provide more details in the error message.
For example, the following messages would be far more useful to the user than the suggestions from the article:
(Score: 1, Funny) by Anonymous Coward on Friday August 18 2017, @09:41AM (1 child)
(Score: 3, Interesting) by Anonymous Coward on Friday August 18 2017, @11:50AM
That was a pretty good error message back in the days.
There were a couple of types of printers, drum printers and chain printers, that had a revolving drum or chain running at very high rpm. So high that they were able to print a line in the time a normal printer could print a character. Because of the high rpm, they created a lot of paper dust, and had to be cleaned often with isopropyl alcohol.
Anything running at high rpm generates heat, and both paper dust and alcohol is flammable. In normal operation the paper was moving, and they wouldn't heat the same point continuously for long enough to ignite it.
These printers had two error lines: Offline and Paper jam. This gives four combination:
Not offline, no jam: Printing fine.
Offline, no jam: Printer was set to offline manually.
Offline, jam: Paper jammed and went offline automatically. Fix the jam and hit the online switch
And the last combination:
Paper jam, not offline: The paper is stuck, but the printer is still printing and generating heat, but because the paper cannot move, the temperature increases quickly.
The console would show the "lp0 on fire" error message and the operator would rush into the printer room, hoping that he could press the offline button before the paper caught fire.
Modern printers don't do this, but the combination of "the paper is stuck but I'm still printing" is not a valid situation, so the error message has remained. Though Linux changed it to something like "on fire, eh?"
(Score: 4, Funny) by DannyB on Friday August 18 2017, @03:37PM (1 child)
Your error message should not merely indicate failure, your program should try to take action to correct the problem.
Error: unable to format drive A:, formatting drive C: instead.
To transfer files: right-click on file, pick Copy. Unplug mouse, plug mouse into other computer. Right-click, paste.
(Score: 3, Funny) by aristarchus on Friday August 18 2017, @09:09PM
That's no Error, it's an act of mercy, a coup d'grace!
(Score: 2) by frojack on Friday August 18 2017, @06:26PM
There are a million ways to fail, and (usually) only one way to succeed.
Software (if written professionally) takes into account as many of those as possible.
Every check for proper data/outcome/format/yadda-yadda has a separate error message.
Often there is no value to the end-user of knowing the exact reason the print failed. Because there's nothing they can do about it anyway.
So you give clear messages where the user CAN act, and tech support unique ID messages where the user can't fix it.
Tech support need a unique-ish value to track it to an exact line of code.
No, you are mistaken. I've always had this sig.
(Score: 1) by mobydisk on Friday August 18 2017, @06:43PM
YES! I wish I had mod points! The article is completely wrong: it recommends error messages that provide no useful information. The author says that "Printing failed" is bad but "Printing failed. Please check your printer" is good. No! How about "Printer OFFICE14 is offline" or "Paper jam on printer OFFICE14"
Really, this is about programmers simply not following best practices. If you call a function, and it returns an exception object with a message "Paper jam" why would you write code that says this:
causeOfError = printer1.Print(document1);
if (causeOfError != null) Display("Something went wrong.")
JEEEZ!!! Instead, write:
if (causeOfError != null) Display("{printer1.name} had error {causeOfError}");
(Score: 2) by el_oscuro on Friday August 18 2017, @11:42PM
Just finished nuking systemd from my Kali box, and replacing it with sysinit.
The reason why? Shitty error handling. I installed Nvidia drivers for cuda support, and they appeared to install OK. After the reboot, no desktop, no SSH, nothing. Eventually I was able to boot into maintenance mode and remove the drivers. After rebooting again, I still couldn't get my desktop and I got:
systemd.logind failed to start. please run systemctl status systemd.logind for more info.
Running the systemctl status systemd.logind command:
"systemd.login failed to start"
I couldn't even get anything meaningful with stack trace, and google was no help. So I nuked it from orbit just to be sure.
SoylentNews is Bacon! [nueskes.com]