This course recommended the following best practices when writing error messages:
- 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.