Message-Design Framework

Before you design a message or alert, use this framework to consider what your user needs to know and what they should do next.

Message Design Framework

Step 1: Answer These Questions

Before putting pen to paper, think about what you’re trying to say and why. Use the questions below as a framework to help you regroup and organize what you’re trying to convey.

Who’s it for?
Why are we reaching out?
When are they receiving it?
Why does this matter to the user and how urgent is it?
What triggers it?
When does the user receive it in relation to the trigger?
What do we want the user to do when they see it?
How else are we telling them, if anywhere?
What other info does the user need to know?
What are the questions a user will have and can we answer them?
How do we want the user to feel after getting it?
Other considerations (e.g., privacy, legal)

You can also find these questions in a spreadsheet on the Product Content Strategy wiki page.

Step 2: Design the Message

Now, craft a message that considers the answers above to help the user understand what’s going on and what they need to do next.

Always make sure to get your messages approved by compliance or legal. If you’re unsure if you need approval, talk to your product owner.

Step 3: Test for Understandability

Put the message in front of a few folks, ask them what they think it means, and see if they have any additional questions. Consider using the highlighter test to identify problematic language.

Examples

The examples below show how to apply the message-design framework to commonly encourtered errors and messages in our products. You may also use these examples as a starting point when crafting your own messages.

MDS 404 Page

Scenario: A page is missing on the MDS site or a user mistyped a URL.

Question	Answer
Who’s it for?	Anyone using the Design System documentation website.
Why are we reaching out?	What the user is looking for no longer exists.
When are they receiving it?	Immediately.
Why does this matter to the user and how urgent is it?	Because they need it to do their job, urgency depends on context.
What triggers it?	When they try to load a page or file that doesn’t exist.
When does the user receive it in relation to the trigger?	At the same time.
What do we want the user to do when they see it?	Check to make sure they are at the right URL and use the site navigation to find what they are looking for.
How else are we telling them, if anywhere?	—
What other info does the user need to know?	How to search for the content they’re attempting to access.
What are the questions a user will have and can we answer them?	Did the Design System remove this content or rename it? How can I search for this content?
How do we want the user to feel after getting it?	Confident about what to do next.
Other considerations	—

Draft Message

It looks like the page or file you’re trying to view doesn’t exist. Check the URL, or use the site navigation to find it. If you need additional help, send us a note at [email protected].

Updates to Expenses Form in Retirement Manager

Scenario: The Retirement Manager team refactored the language and fields for its expenses form based on feedback from users that its copy was unclear. Because users may have entered expenses using the old form in previous sessions (and their inputs would autofill into the new format), we wanted to make sure they review their information.

Question	Answer
Who’s it for?	For return users that have entered expenses in previous sessions.
Why are we reaching out?	We needed to make some changes to the expenses entry form. Because we made a change to something users have already entered/seen, we want to call out that they should verify all form fields are correct before moving forward.
When are they receiving it?	As soon as they get to the expenses page, after the change to the form was made.
Why does this matter to the user and how urgent is it?	Because we want to make sure their strategy accurately reflects their situation, and if inputs are wrong, they should correct them. Expenses won’t make or break a strategy, but they should still check to make sure everything is accurate.
What triggers it?	Coming to the expenses page via the normal workflow.
When does the user receive it in relation to the trigger?	Immediately.
What do we want the user to do when they see it?	We want them to understand that we made changes to the form; we also want them to review the information they entered to ensure its accuracy.
How else are we telling them, if anywhere?	—
What other info does the user need to know?	That they need to review their entered expenses.
What are the questions a user will have and can we answer them?	What changes did you make? How does this affect my advice? What if I don’t want to do this?
How do we want the user to feel after getting it?	That they understand what they need to do and that reviewing their expenses is to their benefit.
Other considerations	Any language that could be perceived as advice must be reviewed and approved by compliance.

Draft Message

We made a few changes to the way we display expense information. Because you’ve previously entered one or more expenses, we recommend you review your information below and make any updates, if necessary, so Our Advice can accurately reflect your situation.

Link Template