The content in our products and messages shape how our users perceive and use our product to get things done. Our writing must help our users understand and take action.
Headings and subheadings in our interfaces have three goals:
- Help users identify their place.
- Help users understand how things are organized.
- Help users predict what actions they can take.
Some specific guidelines for writing headings and subheadings:
- Be concise. Headings and subheadings should be scannable and use only as many words as needed to convey their meaning.
- Write in sentence case. Sentence case makes it feel less stiff and formal.
- Don’t use punctuation like periods or semicolons.
For labels and microcopy, prioritize short and actionable content by removing articles like “the,” “this,” and “an.”
Sentences should provide real value and next steps for our users. They help users cycle between “What’s going on?” and “What do I do next?”
Some specific guidelines for writing sentences:
Start sentences with strong verbs that help users understand what they will do. Include what the outcome of the action will be.
Look for combinations of verbs and nouns that can be replaced by a single verb.
Give users confidence about what they should do.
Buttons are one of the most important elements in our digital platforms. Most actions and conversions are the direct result of the user clicking a button, and the labels used in buttons help users understand what actions are possible and are at the point when a decision becomes an action.
Always write button labels in sentence case.
When buttons enable user actions, the formula is verb + noun.
When buttons are used as calls to action in confirmations, the formula verb + noun doesn’t have to be followed. Instead, use a verb to clearly convey outcomes, by connecting action to outcome.
When buttons support conversion goals, the formula is value + relevance.
Instead of writing about what the user does (the action), write about what the user gets (the value). Then, make it more immediately relevant to the specific conversion context.
The length of a button label when the button’s purpose is conversion isn’t usually a problem.
Further reading:
Buttons can also be an opportunity to use microcopy to create a more positive experience (particularly in negative situations) by making the interface more human. If it’s appropriate, break the rules and explore ways to match the user’s feelings without assigning emotion.
* This isn't a yes/no example, because Get help is a perfectly sensible button label. If every button label tried to be clever, it would get tedious fast.
Further reading:
Links should provide information about what to expect about the associated actions or destination. Users should be able to predict what will happen as a result of clicking a link.
- Want to add repositories? Click here.
- See this page for how to add repositories.
- See documentation for how to add repositories.
Links in full sentences shouldn’t link the whole sentence, but instead only the text that describes the outcome of clicking the link.
- Learn how to create your first batch change.
Links that aren’t in full sentences should be treated similarly to buttons, and use the verb + noun pattern. Don’t punctuate, except with question marks.
Error messages have three goals:
- Explain simply and clearly that there is a problem and what that problem is.
- Provide a solution so that users can return and complete the process immediately.
- Turn the delay into an experience that is as pleasant as possible.
Some specific things to keep in mind when writing error messages:
Keep it conversational. Adjusting the tone of voice to be more formal rather than casual is appropriate, but use restraint.
Again, keep it conversational. We’d never say “error!” in conversation if we didn’t understand something.
Confirmation messages and dialogues are shown when users take an action that can’t be undone, or is difficult to undo.
Confirmation messages should:
- Give the users a chance to confirm or cancel their action
- Be shown in response to a single action
- Always include one or two calls to action
Confirmation message titles should:
- Ask if they want to continue, using a
verb+nounquestion. - Write in sentence case. Sentence case makes it feel less stiff and formal.
- Don’t use punctuation like periods or semicolons, other than a question mark.
Confirmation message body content should:
- Use plain language to explain action is irreversible or difficult to undo.
Confirmation message calls to action should:
- Clearly convey outcomes, by connection action to outcome.
Success messages are shown to users in response to an action they performed, when it succeeds.
Success messages have three goals:
- Provide certainty to the users that the action was completed, and that everything is okay.
- Provide next steps for users, whether optional or mandatory.
- Provide positivity. When things go well, we can magnify the positive feeling and create affinity for our experience.
Some specific things to keep in mind when writing success messages:
While it’s important to provide certainty that what the user wanted to do actually happened, it doesn’t need to be in the template “X successfully completed.” Sometimes, this certainty can even be implicit.
Imagine if we let people share a book recommendation. When the recommendation is sent, we need to show a success message so they can be confident the recommendation was delivered.
Empty states are everywhere. They appear when there’s nothing to show. Sometimes, they appear when the user has yet to add something to a set of items. Other times, they appear when they try to find something and can’t.
An empty state is a chance to educate users about what’s supposed to be there, what can be done there, and how it will provide value to the user.
Some specific guidelines to keep in mind when writing content for empty states:
Avoid using negative words or phrases. Empty states are transitional and reveal potential. Say what’s supposed to be here, or what can be done here, and how it will help them.
If relevant, tell users exactly how to start using a feature and provide an action they can take.
- Your saved searches will appear here. Create your first saved search!
Placeholders appear in form inputs before the user enters text. As a general rule of thumb, placeholders should be avoided except in very specific situations covered below.
Use placeholders for:
- Fields we really want users to complete.
- Fields that users might not understand.
Don’t use placeholders as:
- Labels for form input fields.
- Formatting guidelines.
We use a few different approaches to placeholders.
When the response to an input field might be from a wide range of options, placeholders can be used to reduce the number of choices and provide guidelines for how to respond to the field.
Sometimes, an example will make it easier for users to understand how to answer a field. Avoid this if you can, but if the field is new or unfamiliar it can be a useful tool.
Sometimes, our users need a bit of help. Helper messages help us support our users when they’re filling out forms or taking an action.
Some specific guidelines for writing helper messages:
Before adding helper messages, ask whether users actually need help. The more messages we include on a page or form, the more intimidating it appears to our users.
This is particularly important for helper messages on input fields.