Writing Error Messages Checklist

  • Identify the cause of the error.
    • If the user entered an invalid value, specify the invalid value.
    • Specify requirements and constraints, such as required permissions or minimum RAM.
  • Explain to fix the problem.
    • When appropriate, provide an example to help demonstrate the fix.
  • Write clearly.
    • Be concise, not wordy. However, don't be so concise that the resulting error message becomes cryptic.
    • Avoid double negatives and exceptions to exceptions.
    • Aim the message at the appropriate target audience. Words appropriate for software engineers are often inappropriate for non-technical users.
    • Use terminology consistently. For example, don't use the termΒ directoryΒ in one part of an error message and aΒ folderΒ in another part.
    • Format long error messages carefully, possibly using progressive disclosure or links to expanded documentation.
    • Set a positive tone.
    • Don't be overly apologetic.