Actionable language
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
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.
Microcopy
For labels and microcopy, prioritize short and actionable content by removing articles like “the,” “this,” and “an.”
Sentences
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:
Put action before outcome
Start sentences with strong verbs that help users understand what they will do. Include what the outcome of the action will be.
Use verbs instead of verb-noun phrases
Look for combinations of verbs and nouns that can be replaced by a single verb.
Don’t use permissive language
Give users confidence about what they should do.
Buttons
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.
Buttons for action
When buttons enable user actions, the formula is verb + noun.
Buttons in confirmations
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.
Buttons for conversion
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 as microcopy
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
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.
No
- Want to add repositories? Click here.
- See this page for how to add repositories.
- See documentation for how to add repositories.
In sentences
Links in full sentences shouldn’t link the whole sentence, but instead only the text that describes the outcome of clicking the link.
Yes
- Learn how to create your first batch change.
Outside of sentences
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
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:
Write without rigidity
Keep it conversational. Adjusting the tone of voice to be more formal rather than casual is appropriate, but use restraint.
Write without using the words error or failure
Again, keep it conversational. We’d never say “error!” in conversation if we didn’t understand something.
Confirmation messages
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
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
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
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:
Talk about or to the user, not about the action
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
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:
Remember, empty states aren’t a bad thing
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.
Provide a next step
If relevant, tell users exactly how to start using a feature and provide an action they can take.
Yes
- Your saved searches will appear here. Create your first saved search!
Placeholders
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.
Categories
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.
Examples
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.
Note that when a placeholder is used for an example, it does not replace the input label, but rather provides clarification.
Helper messages
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:
Do users need help?
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.
Be concise
This is particularly important for helper messages on input fields.
Writing about use cases
When prompting users about or writing about our 5 company uses cases, we can’t assume that users are familiar with our terminology: a developer does not necessarily have in mind that they are using Sourcegraph for “Code Health”.
Instead we can use this more intuitive (but less accurate) language:
| Sourcegraph use case | “You are using Sourcegraph to…” |
|---|---|
| Developer Onboarding | Understand a new part of the codebase |
| Code Health | Improve codebase quality |
| Code Reuse | Find code to reuse |
| Incident response | Respond to incidents |
| Code security | Fix security vulnerabilities |
Providing additional resources for troubleshooting
When communicating that a problem is resolvable in mulitple ways, provide an external link to the docs page that cover all cases.
Be explicit about linking to troubleshooting
Avoid using simple ‘learn more’ that would be too broad for this case.
Yes
- Results may be incomplete. Troubleshoot
- Cannot connect. Repair connection
No
- Results may be incomplete. Learn more
Don’t overpromise
Use phrases that suggest that user can learn more about the known problems and how to fix them. Avoid promising a simple fix or a direct help.
Yes
- Learn how to troubleshoot