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 pkrasimirov on Friday August 18 2017, @10:42AM (4 children)
First let's differentiate between logs and developer traces. Log message is something the system tell the user/admin. It should be translated to the appropriate language and has to have these 3 artifacts:
1. What happened
2. What's the impact
3. What should be done to remedy the situation
Example: "No free space on /tmp/report.tmp. Custom reports cannot be generated. Please free some space, restart the application and retry"
It is also important to log the above such message once and not spam the user.
Blame is completely irrelevant.
Developer traces are for the solely consumption of the said developer or team. It is not produced by default, when turned on it can spam as much as the developer feels need, and it should be comprehensible only for them. It may contain sensitive data such as passwords and credit card numbers. It is for troubleshooting only and it is irreplaceable for systems where a debugger cannot be simply attached.
The third ones, audit logs, are an entirely different thing and technically not a log. It is a write-only stream to tamper-proof storage with these artefacts: 1) When 2) Who 3) Op (CRUD) 4) old_value 5) new_value. It should run transactional with the main operation. Failure to audit log should lead to failure of the entire transaction.
One more thing. Nobody cares about the "severity" except for filtering purposes. Compare "[ERROR] Cannot find log config file, will log to console" and "[WARNING] /sbin/init: Unexpected file size change".
(Score: 2) by maxwell demon on Friday August 18 2017, @10:58AM (1 child)
I think you want to read about the origin of the term "log".
In other words, a log in the truest sense possible (except that it doesn't contain ship speeds).
The Tao of math: The numbers you can count are not the real numbers.
(Score: 2) by pkrasimirov on Friday August 18 2017, @11:17AM
I meant not a log in a plain text file. It is a log.
(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.