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: 3, Insightful) by romlok on Friday August 18 2017, @12:36PM (1 child)
In terms of technical debugging, perhaps, but it's certainly not irrelevant if you want the amicable cooperation of your users. People don't like to be blamed for things, especially when they didn't know better, or (as is often likely with complex computer systems) when it wasn't their fault in anything but the most vague terms.
Consider if your example error message had been worded thus:
"You used up all the space on /tmp/report.tmp. Custom reports cannot be generated. Please free some space, restart the application and retry"
This wording carries the same overall meaning, but puts blame on the user for the lack of space. When a user is encountering errors while trying to get on with their work, they're not going to react kindly or co-operatively to being accused of things by the computer - even (especially!) if it was indeed their fault.
(Score: 3, Insightful) by krishnoid on Friday August 18 2017, @08:38PM
Besides, I just *asked* the computer to put files there. It should have known better than to fill it up and then complain to me about it.