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: 0) by Anonymous Coward on Friday August 18 2017, @09:34AM (10 children)
printf("something isn't as it should be!\n");
???
(Score: 0) by Anonymous Coward on Friday August 18 2017, @09:48AM (2 children)
printf("Should not ever get here - abort\n"); exit(666);
(Score: 0) by Anonymous Coward on Friday August 18 2017, @11:53AM (1 child)
/* Cannot possibly happen */
while(1) printf("Bugger\n");
Support ticket 12345:
User reports that his screen is filled with the word "bugger".
(Score: 2) by tangomargarine on Friday August 18 2017, @02:49PM
Trivial Updates:
October 31 - Fixed a bug that would briefly turn you into CDMoyer, output the word "balls" and then log you out.
"Is that really true?" "I just spent the last hour telling you to think for yourself! Didn't you hear anything I said?"
(Score: 4, Insightful) by maxwell demon on Friday August 18 2017, @09:53AM (5 children)
No, error messages should go to stderr.
The Tao of math: The numbers you can count are not the real numbers.
(Score: 0) by Anonymous Coward on Friday August 18 2017, @09:58AM (4 children)
Or written to c:\log.log
(Score: 0) by Anonymous Coward on Friday August 18 2017, @10:03AM (3 children)
(Score: 0) by Anonymous Coward on Friday August 18 2017, @10:25AM
"There has been an undetectable error in your system. Note: "your" system. Microsoft assumes no liability, expressed or implied. You may want to check on your children. NO, I cannot tell you why. There has been an undetectable error in your system."
I always wondered, how did they know? And it was sad about the children. Microsoft! Ha! Anomoly??
(Score: 0) by Anonymous Coward on Friday August 18 2017, @07:44PM
My favorite, from before USB was a thing:
No keyboard detected. Press enter to continue.
(Score: 2) by maxwell demon on Friday August 18 2017, @08:10PM
"Press any key when ready", the most misleading message of all times: You couldn't press any key; keys like Shift, Ctrl and Alt wouldn't work.
The Tao of math: The numbers you can count are not the real numbers.
(Score: 0) by Anonymous Coward on Friday August 18 2017, @10:08AM
You forgot to check the error code from your printf() call...