Checklist for writing effective messages

User perceptions of a software product are strongly influenced by how well messages convey relevant information and help the user solve a problem. Use the following checklist to ensure that messages are clear, accurate, complete, and helpful.

  • Write accurate messages:
    • Ensure that all facts in the message are accurate.
    • Avoid product names and versions because they change over time.
  • Avoid telling users to call a support organization or system administrator:
    • Check whether there are alternative solutions.
    • Ask users to check documentation, Web sites, and so on to find solutions.
  • Do not blame the user:
    • Write messages so that they don’t appear to blame the user, even if it the cause is a user error.
    • Avoid “doomsday” phrases such as catastrophic failure or fatal error.
  • Use clear language:
    • Check for ungrammatical or incorrectly punctuated sentences.
    • Avoid garbled, long (over 25 words), or convoluted sentences.
    • Check for unnecessary passive voice.
    • Avoid abstract language, general language, and jargon.
    • Use a consistent style and word usage.
    • Always use full sentences with correct punctuation.
    • Use nouns after command and API names, for example, the BaseException class. (class is the noun.)
    • Do not leave out articles such as a, an, or the.
  • Provide complete information:
    • Ensure that each message is needed in the system. Don’t display a message when the code should handle the issue.
    • Provide all the instructions for resolving a problem in one message whenever possible.
    • If the user actions are too long or topics for the appropriate corrective actions exist elsewhere, provide a link from the message to other appropriate topics.
    • Add explanation, user response, and system programmer response sections to all messages.
    • Do not give simplistic user actions such as “See the log files” without more guidance. For example, if you ask users to see log files, tell them where to look in the directory structure to find the log and what to look for in the log.
    • Provide examples for commands, APIs, or other code unless the code is extensive or complicated.
    • Do not expose unnecessary information such as documenting system actions that do not affect the user, providing information that is too detailed for the target audience, and describing internal workings that the user has no control over. This information should be logged only in a trace for support.
Parent topic: Developing message help