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 Azuma Hazuki on Friday August 18 2017, @04:17PM (1 child)
This shouldn't be hard. Say what happened as clearly as possible (and optionally also in geek-speak), why it happened (ditto), and what to do.
"Error: Printing failed. 8.5 x 11 paper was not detected in paper tray. Please load paper and try printing again" -- much more informative that "PC Load Letter."
And for a more complex case:
"Error: Device driver for device nVidia GeForce GTX1060 has crashed.
Please show your administrator the following: "BUGCHECK 0x000000f7: A driver has overflowed its stack-based buffer: Dump: 0x00000000 0x00f62748 0x23004756 0xDEADBEEF Location of core file at C:\WINDOWS\MEMORY.DMP.
When you have finished copying this message, please press Return/Enter and Windows will attempt to reboot. If the error recurs, or if Windows is not able to repair itself, please shut the computer down and have a qualified professional perform maintenance."
I am "that girl" your mother warned you about...
(Score: 2) by maxwell demon on Friday August 18 2017, @08:14PM
But wouldn't fit on the tiny printer display.
The Tao of math: The numbers you can count are not the real numbers.