Skip to main content

Writing effective messages

Overview​

Effective messages are essential for a positive user experience. They guide users, help them prevent or recover from issues, and build trust by providing timely, understandable feedback. This page outlines principles for writing user-centered messages.

For detailed information on specific UI components used to display messages and how to implement them, see Validation and messaging mechanisms.

User-centered messaging​

When writing any message, always aim to be:

  • Clear and concise: Use plain language and get straight to the point. Avoid jargon or technical terms users might not understand.
  • Helpful: Provide users with the information they need to understand the situation and, if necessary, take appropriate action.
  • Timely and relevant: Ensure messages appear when and where they make the most sense in the user's workflow.
  • Empathetic and respectful: Write in a supportive tone. Avoid blaming the user, even if an error resulted from their action. Focus on the solution.
  • Consistent: Use a consistent voice and terminology across all messages to build familiarity and trust.

Understanding message intent​

Different situations call for different types of messages. Understanding the intent helps you craft the right communication:

  • Success messages: Inform users that an action or process they initiated (or that happened automatically) has completed successfully.
    • Goal: Reassure and confirm.
  • Error messages: Alert users that an action could not be completed, a problem has occurred, or input is invalid, often preventing them from proceeding.
    • Goal: Clearly explain the problem and guide the user toward a solution.
  • Warning messages: Notify users about potential issues or conditions that might not immediately block them but could cause problems later if not addressed.
    • Goal: Inform and allow users to make choices or take preventative action.
  • Informational messages (general updates): Provide helpful context, guidance, or system status updates that aren't critical but can aid task completion or understanding.
    • Goal: Offer non-critical, useful information.

Contexts for messages​

Users encounter messages in various contexts. Adapt your writing accordingly:

  • Responding to field validations:

    • Context: User input in a form field needs correction.
    • Writing focus: Clearly identify the incorrect field and explain what's needed (for example, "Enter your email address", not just "Invalid input").
    • Display: Often shown near the field itself.

  • Following actions on a page:

    • Context: User completes an action (for example, saving, submitting, deleting).
    • Writing focus: Confirm success, or explain critical errors or necessary confirmations related to the action.
    • Display: May use modals for critical information or toasts for less intrusive confirmations.

  • Providing general system updates or feedback:

    • Context: The application needs to inform the user about system status, background processes, or less critical app-wide information.
    • Writing focus: Be brief and informative. Ensure the message is understandable even if the user is focused elsewhere.
    • Display: Often use non-intrusive methods like toasts.

Best practices for writing messages​

Be specific, not generic​

If you know what went wrong, say so. Avoid vague messages like "An error occurred" or "Something went wrong" if more detail can be constructively provided.

Do describe the problem and then propose a solution.
Don't use vague statements that hide the error's specific cause or offer no clear next step.

For error messages: guide to resolution​

  • Explain clearly: Tell the user what happened and, if possible, why it happened in simple terms.
  • Provide actionable steps: If there's something the user can do to fix it, tell them exactly what.
  • Offer a way out: If the user can't fix the problem, suggest next steps (for example, "Try again later," "Contact support," or provide a link to a help article).
  • Reassure if possible: If some parts of their work were unaffected (for example, "Your draft was saved"), let them know.
Do give actionable instructions that enable the user to correct the input immediately.
Don't use ambiguous or overly general terms that offer no clear path to resolution.

Maintain an appropriate tone​

For error messages, adopt a service-oriented and supportive tone: avoid assigning blame, simply describe the problem, and then propose a solution, focusing on what's possible rather than limitations. While friendly and conversational, ensure the tone remains clear and empathetic, especially when users might be frustrated.

For more information, see Adjusting tone.

Generally, avoid "please." Use it only if the software is at fault, presents an issue we can't directly help solve, or asks for a particularly inconvenient user action.

For more information, see Common actions terminology.

Do say what's possible instead of what's not.
Don't blame the user.

If more detailed instructions or information are needed, provide a clearly labeled link (for example, "Learn how to fix this", not "Click here").

Responsiveness​

All message containers in Jutro are fully responsive. As a content author, your primary contribution to a good responsive experience is through conciseness.

  • Keep messages brief: Shorter text is easier to read and less likely to truncate or overwhelm users on smaller screens. This is especially vital for components with limited space, such as toasts.
  • Be mindful of context: Inline notifications and error messages respond to their container panel, and toasts can be made "full-width" in small form factors depending on usage. Well-chosen, concise wording ensures clarity regardless of these adjustments.

Accessibility​

While Jutro toast and inline notifications conform to WCAG 2.1 AA requirements, changes made by the content author can affect accessibility conformance. Follow the accessibility guidance for toast and inline notification.