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

• use wording or a tone that doesn't blame the user use wording or a tone that doesn't blame the user (Score: 0) by Anonymous Coward on Friday August 18 2017, @02:27PM (4 children)

  by Anonymous Coward on Friday August 18 2017, @02:27PM (#555887)

  What if the user is at fault?

• Re:use wording or a tone that doesn't blame the us (Score: 1, Funny) by Anonymous Coward on Friday August 18 2017, @03:02PM

  by Anonymous Coward on Friday August 18 2017, @03:02PM (#555907)

  "Critical PEBKAC detected. Contact the returns department with error code: id-10t. You will be provided with an abacus and a box of crayons."

  Parent

• Re:use wording or a tone that doesn't blame the us Re:use wording or a tone that doesn't blame the us (Score: 2) by maxwell demon on Friday August 18 2017, @03:06PM (1 child)

  by maxwell demon (1608) on Friday August 18 2017, @03:06PM (#555912) Journal

  Cannot be the case.

  Don't write "wrong username or password", as that implicitly blames the user. Instead write "This username/password combination is missing from the database."

  SCNR

  --
  The Tao of math: The numbers you can count are not the real numbers.

  Parent

  • Re:use wording or a tone that doesn't blame the us (Score: 2) by bob_super on Friday August 18 2017, @05:36PM

    by bob_super (1357) on Friday August 18 2017, @05:36PM (#555992)

    You want people to try again and focus harder to avoid mistakes?
    Ask the experts [youtube.com].

    Parent

• Re:use wording or a tone that doesn't blame the us (Score: 2) by Aiwendil on Saturday August 19 2017, @03:49PM

  by Aiwendil (531) on Saturday August 19 2017, @03:49PM (#556383) Journal

  "Unknown user/password combination" - it states just that, the combination is unknown (also covers missinng password database)
  "Unable to log in" - short and sweet, implies computer is at fault (append "please try again" to coax the user into trying again while still implying the fault is computerside)
  "Credentials not accepted" - implies that something failed (apply "please try again" if needed)
  "Credentials not accepted by system" - same as above put alludes system at fault.
  "Unable to synchronize, please retry" - same as above.

  Or my favorite: "Didn't work! Try again?"

  Parent