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 bob_super on Friday August 18 2017, @05:20PM (3 children)
In a previous life as an FAE, I dealt with engineers using pretty specialized tools.
Way too many see the popup with the red cross and five lines of explanation, and close it without reading, before asking me to fix the problem. Many of our error messages were actually pretty detailed and would give you the answer. But the customers didn't realize the tools had progressed since the days of useless "some error occurred" messages.
But then, there were some clearly-ESL messages which had obviously never been reviewed by a native speaker. With enough experience, you can find out whether the coder was Indian or Chinese, because they don't make the same English mistakes.
(Score: 2) by frojack on Friday August 18 2017, @06:17PM (1 child)
Put it all on line, and get google sort it out.
But you need some unique-ish thing to search.
No, you are mistaken. I've always had this sig.
(Score: 2) by bob_super on Friday August 18 2017, @06:22PM
Unique error codes, which you can google with the tool name, are pretty good, if someone already had the same problem.
I tried to lobby to release a database of error codes (where it comes from, why, what to do), but when the tool is over 10GB (now 30) with over 100k files, it's too late to start...
(Score: 2) by maxwell demon on Friday August 18 2017, @08:04PM
Maybe if the user clicks OK too quickly to have possibly read the error message, pop up another box with a short quiz about what the error message they just clicked away actually said. :-)
The Tao of math: The numbers you can count are not the real numbers.