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.
Yes
  • Get started with code search
No
  • Get Started with Code Search.

Microcopy

For labels and microcopy, prioritize short and actionable content by removing articles like “the,” “this,” and “an.”

Yes
  • Install now
No
  • Install this extension

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.

Yes
  • Add repositories from your code host.
No
  • Repositories from your code host will appear here after you add them.

Use verbs instead of verb-noun phrases

Look for combinations of verbs and nouns that can be replaced by a single verb.

Yes
  • Search for your repo to get started.
No
  • Make a search for your repo to get started.

Don’t use permissive language

Give users confidence about what they should do.

Yes
  • Add your repos from your code host and start searching code.
No
  • Add your repos from your code host and you can start searching code.

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.

Yes
  • Create batch change
No
  • Create Batch Change

Buttons for action

When buttons enable user actions, the formula is verb + noun.

Yes
  • Add repo
  • Explore extensions
No
  • Add
  • Explore

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.

Yes
  • Discard changes? Cancel / Discard
No
  • Discard changes? No / Yes

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.

Yes
  • Start searching code now
No
  • Try now

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.

Yes
  • I tried, I’m stuck, I need help

Instead of *

  • Get help

* 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.

No

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.

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.

Yes
  • Password must contain at least 12 characters
No
  • Password format is invalid (minimum 12 characters)

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.

Yes
  • Sorry, we couldn’t save your changes. Try again?
No
  • Failed to save changes.

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 + noun question.
  • 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.
Yes
  • Discard unsaved changes?
No
  • Discard?

Confirmation message body content

Confirmation message body content should:

  • Use plain language to explain action is irreversible or difficult to undo.
Yes
  • This can’t be undone
No
  • If you discard changes, your list will remain unchanged.

Confirmation message calls to action should:

  • Clearly convey outcomes, by connection action to outcome.
Yes
  • Discard changes? Cancel / Discard
No
  • Discard changes? No / Yes

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.

Yes
  • Your new code monitor is now watching for events.
No
  • Code monitor successfully created.

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.

Yes
  • Your saved searches will appear here
No
  • Oops, you have no saved searches

Provide a next step

If relevant, tell users exactly how to start using a feature and provide an action they can take.

Yes
No
  • No saved searches

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.

Yes
  • Search by language, repo, or organization

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.

Yes
  • Input label: Search snippet
    Placeholder: Such as “repo:sourcegraph/sourcegraph”

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.

Yes
  • 8–12 characters
No
  • Password must be between 8–12 characters

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 OnboardingUnderstand a new part of the codebase
Code HealthImprove codebase quality
Code ReuseFind code to reuse
Incident responseRespond to incidents
Code securityFix 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
No

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.