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, 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?"