SoylentNews

How to Write Better Error Messages

posted by Fnord666 on Friday August 18 2017, @08:47AM   
from the delete-all-your-files.-Ok? dept.

MrPlow writes:

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

---

Original Submission

• Re:Users WILL read error messages that are USEFUL (Score: 0) by Anonymous Coward on Friday August 18 2017, @06:57PM

  by Anonymous Coward on Friday August 18 2017, @06:57PM (#556032)

  Error messages should be actionable. Don't just say "syntax error". Say "missing comma after Aardvark".

  The problem with syntax errors is that the actual reason for the error is usually not knowable because the program cannot divine the intentions of the user. All it can really do is look at the current parser state, which is probably completely bogus (the input is already known to be invalid, after all), and try to guess what the user actually meant by it. Computers are notoriously bad at this. Sometimes this works OK, other times it will be completely wrong.

  The parser can explain which part of the input did not match its expectations, and perhaps even what those expectations were. Outside of trivial cases, this will likely require some knowledge of how the parser works for the user to comprehend it.

  Some parsers attempt to re-synchronize after detecting an input error in an attempt to proceed anyway. Again, sometimes this works OK, other times this makes the situation even worse.

  Parent