Overview
This guide includes rules for writing in-product messages. Become familiar with the entries in the Editorial Style Guide first, and then consult the entries here for additional guidance.
This guide is also based on voice and tone guidelines.
In-product messages
We often use the phrase “error message” to describe any kind of pop-up message displayed in our software. And that’s one of the main reasons we end up using the wrong tone when we write these messages
There are four broad types of communications that we provide in these messages:
- Notifications—After or during an event, provide useful but non-critical updates on status or progress.
- Confirmations—Before or during an event, inform people about something that will happen if they continue with an action.
- Warning—Before or during an event, alert people of a potential problem and how to avoid it.
- Error—After an event, tell people about a problem that has occurred and how to resolve it.
Even though they may look similar, each type of message presents information in a different context for the subscriber. They can be positive, neutral, or negative, and the tone and information must match the context. You can find more information on writing for each type of message in the sections below. Also worth noting, where word and character counts are suggested, these are based on English, and will vary in other languages.
General messages
Even though each type of message is used for a different context, they all follow the same general pattern. This keeps the presentation and layout consistent across all messages.
| Message element | Description | Content pattern |
|---|---|---|
| Title (optional) | Don’t repeat the title information in the main content. Important: Don’t state key information in the title. | Sentence case, 3-5 words, 50 characters max, no end punctuation (a question mark is allowed when needed) |
| Main content | State key information; What led to this message…why it happened. Suggest how to proceed. Depending on the message, may suggest how to avoid, how to correct, and/or what should be done now. | Sentence case, 30 words, 200 characters max, use end punctuation (a question mark is allowed when needed) |
| Expanded content (optional) | More detail, explanation of possible solutions, and so on. (This is common in task dialogs for desktop products.) | Sentence case, 35 words, 250 characters max, use end punctuation (a question mark is allowed when needed) |
| Primary action | The button label that recommends the most likely step the subscriber should take. | Sentence case, 1 or 2 words, 20 characters max, no end punctuation (a question mark is allowed when needed) |
| Secondary action (optional) | The button label that recommends the alternative action the subscriber can take, most often “Cancel” or “Go Back”. | Sentence case, 1 or 2 words, 20 characters max, no end punctuation (a question mark is allowed when needed) |
| Tertiary action (optional – infrequent) | Some contexts may offer/require a third option for action. | Sentence case, 1 or 2 words, 20 characters max, no end punctuation (a question mark is allowed when needed) |
| Help link (optional) | Link to an external help document, often using the phrase “Learn more” or posed as a question, “How do I…”. Only used for cases that require detailed info or procedures. | Sentence case, 2-10 words, 50 characters max, no end punctuation (a question mark is allowed when needed) |
General message dialog guidelines
- Use the right tone. The situations that lead to these messages are very different—so it’s important to follow the tone guidelines so you communicate in the right way.
- Informative: Convey the information clearly and concisely.
- Use for: Notifications, AlertsHelpful: Explain the situation in a friendly, conversational tone (but not too casual). Use plain language, and avoid jargon or buzzwords.
- Use for: Confirmations, Warnings.
- Apologetic: Explain what happened in clear, conversational manner. There’s no need to say “sorry” in an error message, but we should accept blame and offer solutions to the problem.
- Use for: Errors.
- Use the title to briefly state key information. Don’t use the title to explain the problem—that’s the purpose of the main content.
- Use we only if it’s something that a human at Autodesk has explicitly done. Example: We recommend a screen size of…
If it’s a system/technical error, don’t use the first person because a person at Autodesk isn’t taking the action. Example: We couldn’t save…
Use appropriate end punctuation at the end of any message that forms a complete sentence.
- Anticipate the subscriber’s pre-existing questions and knowledge.
- Consider the subscriber’s current context within the overall experience.
- Use specific, action-oriented language. Avoid jargon.
Notifications
When to use notifications
Use a notification to inform the subscriber of an event that they should be aware of, but may not require immediate action. These may be the result of a previous action or a system condition or state. Typically, actions aren’t required, although actions may be included (such as canceling the action that triggered the notification).
Subscriber needs
When subscribers receive a notification, they want to know how it’s related to what they did or why they are receiving it. They may also want more control over how/whether they receive these notifications in the future.
Tone
Informative—Convey the information clearly and concisely.
Style
| Message element | Description | Content pattern |
|---|---|---|
| Title | Briefly state the reason for the notification | Sentence case, 3-5 words, 50 characters max, no end punctuation |
| Main content | Provide the key information the subscriber needs to know. What happened? | Sentence case, 30 words max, 200 characters max |
| Expanded content (optional) | More detail, about why they received the notification and what it means for them. (This is common in task dialogs for desktop products.) | Sentence case, 35 words max, 250 characters max |
| Primary action | Most likely step the subscriber should take. (This is often to “Close” or dismiss the dialog.) | Sentence case, 1 or 2 words, 20 characters max, no end punctuation |
| Secondary action (optional) | Additional action the subscriber can take. (This may be a link to more information.) | Sentence case, 1 or 2 words, 20 characters max, no end punctuation |
Guidelines
- Don’t use notifications to convey critical information that requires the subscriber’s attention or action.
- Provide ways to review notification preferences and/or ways to disable, unsubscribe, or prevent similar notifications in the future.
Confirmations
When to use confirmations
Use a confirmation message to provide critical information about something that will happen if a subscriber takes a specific action, then provide options for the next steps. Typically, these options include continue with the action or stop/cancel the action. These messages provide the subscribers with “informed consent” of actions that may result in irreversible changes, such as overwriting a file or losing progress.
Subscriber needs
In this case, people need to know why they’re being prompted (what caused this?) and specifically what will happen if they continue or cancel.
Tone
Helpful: Explain the situation in a friendly, conversational tone (but not too casual). Use plain language, and avoid jargon or buzzwords.
Style
| Message element | Description | Content pattern |
|---|---|---|
| Title | Phrase the title as a question, asking the subscriber if they want to take the action. This doesn’t have to be a complete sentence. | Sentence case, 3-5 words, 50 characters max, use a question mark |
| Main content | Explain what caused this message, and what the implications are. | Sentence case, 30 words max, 200 characters max |
| Expanded content (optional) | Describe what the subscriber’s options are and what will happen if they choose each path. This is often used in larger message boxes for desktop applications. (This is common in task dialogs for desktop products.) | Sentence case, 35 words max, 250 characters max |
| Primary action | The action that’s being confirmed in the title. Button text should match the action in the title. | Sentence case, 1 or 2 words, 20 characters max, no end punctuation |
| Secondary action (optional) | Additional action the subscriber can take. (This is most often to “Cancel” or not take the primary action.) | Sentence case, 1 or 2 words, 20 characters max, no end punctuation |
| Tertiary action (optional – rare) | Some contexts may offer/require a third option for action. | Sentence case, 1 or 2 words, 20 characters max, no end punctuationMessage element |
Guidelines
- Confirmations can be used to display critical information that require the person’s attention.
- Don’t use the generic “Are you sure…” confirmation. Provide a clear reason why they may not want to proceed.
- Don’t use an “X” in title bars of confirmation messages to avoid confusion. One of the buttons should already provide the “Cancel” or “Go back” option.
- Add “anyway” to the primary button label, as in “Continue anyway”
- In some cases, you may want to provide.
- A way to review confirmation preferences and/or a checkbox to disable, unsubscribe, or prevent similar notifications in the future. For confirmations, this is often to “always take the selected action” or “don’t show me this again”.
- A “Save and continue” option instead of “Continue anyway”. However, if the entries contain unfilled required fields, the “Save and continue” option should not be included.
Warnings
When to use warnings
Use a warning message to alert a person of a potential problem if a subscriber takes a specific action, then provide options for next steps. Warnings should be used to help subscribers avoid unreasonable delays irreversible changes or data loss. This is like a confirmation (see above) but used for actions with more severe outcomes.
Subscriber needs
People need to easily understand the potential outcomes of the action (or inaction) described in the message. What are their alternatives? What is the recommended action, if any?
Tone
Helpful: Explain the situation in a friendly, conversational manner (but not too casual). Use plain language, and avoid jargon or buzzwords.
Style
| Message element | Description | Content pattern |
|---|---|---|
| Title | Clearly state the warning. | Sentence case, 3-5 words, 50 characters max, no end punctuation |
| Main content | Explain what most likely caused the message and what the implications are. | Sentence case, 30 words max, 200 characters max |
| Expanded content (optional) | Describe what the subscriber’s options are and what will happen if they choose each path. Whenever possible, provide advice on how to avoid this situation again. (This is common in task dialogs for desktop products.) | Sentence case, 35 words max, 250 characters max |
| Primary action | The most likely step the subscriber should take. | Sentence case, 1 or 2 words, 20 characters max, no end punctuation |
| Secondary action (optional) | Additional action the subscriber can take, if available. | Sentence case, 1 or 2 words, 20 characters max, no end punctuation |
| Tertiary action (optional – rare) | Some contexts may offer/require a third option for action. | Sentence case, 1 or 2 words, 20 characters max, no end punctuation |
| Help link (optional – rare) | Link to an external help document, often posed as a question. Only used for cases that require detailed info or procedures. | Sentence case, 2-10 words, 50 characters max, no end punctuation (a question mark is allowed when needed) |
Guidelines
- Don’t start the title or message with the word “Warning”.
- Design warnings to avoid the need for Help. Ordinarily users shouldn’t have to read external text to understand what will happen, unless the solution requires several steps.
- Provide ways to review confirmation preferences and/or a checkbox to disable, unsubscribe, or prevent similar notifications in the future. For confirmations, this is often to “always take the selected action.”
Errors
When to use errors
Use an error message to tell people about a problem that already occurred and how to resolve it (if possible). Typically, errors indicate a failure, either caused by a subscriber’s action or by our software. Make sure the error is timely (shown in relation to the action), readable (descriptive, concise, and clear), and corrective.
Subscriber needs
People need to know what happened, how to get back on track, and how to avoid the situation that triggered the error in the future. It’s important not to blame the subscriber in the description, even if the error stemmed from an action they took.
Tone
Apologetic: Explain what happened in a clear, conversational manner. There’s no need to say “sorry” in an error message, but we should accept blame and offer solutions to the problem.
Style
| Message element | Description | Content pattern |
|---|---|---|
| Title | Clearly state the error. | Sentence case, 3-5 words, 50 characters max, no end punctuation |
| Main content | Explain what most likely caused the error and what the implications are. | Sentence case, 30 words max, 200 characters max |
| Expanded content (optional) | Describe what the subscriber’s options are and what will happen if they choose each path. Whenever possible, provide advice on how to avoid this situation again or steps to correct or work around the problem. (This is common in task dialogs for desktop products.) | Sentence case, 35 words max, 250 characters max |
| Primary action | The most likely step the subscriber should take. Avoid using “OK” as the primary action. | Sentence case, 1 or 2 words, 20 characters max, no end punctuation |
| Secondary action (optional) | Additional action the subscriber can take, if available. | Sentence case, 1 or 2 words, 20 characters max, no end punctuation |
| Tertiary action (optional – rare) | Some contexts may offer/require a third option for action. | Sentence case, 1 or 2 words, 20 characters max, no end punctuation |
| Help link (optional – rare) | Link to an external help document, often posed as a question. Only used for cases that require detailed info or procedures. | Sentence case, 2-10 words, 50 characters max, no end punctuation (a question mark is allowed when needed) |
Guidelines
- Avoid using “you” in the description of what happened. It can sound like we are blaming the subscriber.
- Don’t start the title or message with “Sorry” or “We’re sorry.” And never say “Oops.”
- Don’t include error codes (such as Microsoft errors) in the description, unless it is helpful for the subscriber finding a resolution.
- If possible, use the title to identify the command or feature from which the error originated.
- Design error messages to avoid the need for Help. Ordinarily users shouldn’t have to read external text to understand and solve the problem, unless the solution requires several steps.
- Provide links to online Help for error messages that you can’t make specific and actionable. By doing so, you can provide users with additional information that you can update after the program is released.
Buttons
Follow the Weave recommendations for button labels: Refer to the Content pattern section in the Weave Buttons topic (must be connected to VPN).
Note on the use of ‘Continue’, ‘Would you like to continue’ and so on, as a button label: Restructure the message to avoid the need for ‘Continue’, ‘Would you like to continue’ and so on, as a button label. Restructure the message so the button label follows the guidelines in the Content pattern section in the Weave Buttons topic (must be connected to VPN).
Example
Message
Assigning the same color to the snap styles can make it difficult to identify the active snap mode.
Button labels
Yes: Assign Color Cancel
No: Continue Cancel
Desktop cloud message repository
The Desktop cloud message repository (access required) is a catalog of message strings that were finalized through voice and tone content critiques. Use it to find messages similar to the message you’re working on.
Error handling messages influence how a customer feels about working in the cloud. Providing meaningful and consistent messaging across products delivers a superior customer experience.
Please send corrections or suggestions about the message repository to Martin Chesnay at martin.chesnay@autodesk.com.