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, @10:00PM

  by Anonymous Coward on Friday August 18 2017, @10:00PM (#556142)

  There should be a distinction between anticipated error messages and un-anticipated. For example, if you can detect the PC or application is out of memory, then you can tell the user that the application doesn't have enough computer memory to continue. However, if you go to allocate memory and the allocator API itself returns "unknown error" or the like, then you cannot give a clear description of the problem to the user. The programmer using the API cannot tell either (unless it happens under testing and experiments can be done). The best one can do is guess and suggest: "This application encountered an unanticipated problem while trying to request more computer memory. It's possible your computer's memory is full." Being caused by lack of memory is only a guess. An "unknown error" by a memory allocator could be caused by defective RAM, cosmic rays, defective bus, defective allocator logic (api bug), etc.

  Parent