Stories
Slash Boxes
Comments

SoylentNews is people

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

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

 
This discussion has been archived. No new comments can be posted.
Display Options Threshold/Breakthrough Mark All as Read Mark All as Unread
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
  • (Score: 4, Interesting) by coolgopher on Friday August 18 2017, @11:01AM (2 children)

    by coolgopher (1157) on Friday August 18 2017, @11:01AM (#555830)

    General failure reading drive A:
    (A)bort, (R)etry, (I)gnore?

    Or, more poetically, https://w2.eff.org/Net_culture/Folklore/Humor/abort_retry_ignore.poem [eff.org]

    Starting Score:    1  point
    Moderation   +2  
       Insightful=1, Interesting=1, Total=2
    Extra 'Interesting' Modifier   0  
    Karma-Bonus Modifier   +1  

    Total Score:   4  
  • (Score: 3, Informative) by Fnord666 on Friday August 18 2017, @12:17PM (1 child)

    by Fnord666 (652) on Friday August 18 2017, @12:17PM (#555847) Homepage

    General failure reading drive A:
    (A)bort, (R)etry, (I)gnore?

    Or, more poetically, https://w2.eff.org/Net_culture/Folklore/Humor/abort_retry_ignore.poem [eff.org]

    I thought the classic error message was
    Keyboard not found. Press F1 to continue.

    • (Score: 0) by Anonymous Coward on Friday August 18 2017, @06:47PM

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

      I thought the classic error message was
      Keyboard not found. Press F1 to continue.

      I think this is very elegant. "We don't think you have a keyboard. Once you have fixed that and can push F1, you may continue."

      I had thought the class error message was, "PC Load Paper"