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: 1, Interesting) by Anonymous Coward on Friday August 18 2017, @07:32PM
I actually solved this problem with my users by making up error codes that sound technical. I borrow from the style of actual C library error codes, and sometimes I use error codes straight out of C like ENOENT. Make sure it starts with the letter E, is all caps, and is cryptically just enough like something that could be one or two English words.
They remember it every single time. The first time I did that was out of sheer frustration. Then, to my complete and utter surprise, users started mentioning this specific EFIZBAZ error code, telling me exactly where the problem was. It was bliss! Except for the fact that without reading TFA, I'm going to bet the author is going to say that what I found is unpossible.
Give the user a short, clear, concise explanation of what went wrong. The user will never fucking even try to read it!
Give the user EBINWIDGET. They report it correctly every single fucking time! And I must have 50 different, completely made up error codes like that running around by now!