Writing style

Our writing style prescribes the characteristics of our voice and tone. It is made up of four principles that reflect the way we want to communicate with our users.

We use US English spelling and sentence case for everything, including titles and buttons.

Speak human

Speak the user's language, not the computer's. Use a standard vocabulary and a natural tone, and be sure to employ contractions so sentences flow naturally. Try to delight the user with positive phrasing as well as a conversational voice. Last but not least, read your copy aloud to make sure it sounds natural.

Bad Bad

There are no options available to you right now. Please contact your JIRA Administrator for help.

Good Good

Unfortunately you can't create a new board. You need to talk to your JIRA administrator to create a board, or ask for permission to do so yourself.

Improvements explained
  • Soften the blow – the bad message makes the user feel small and insignificant
  • Give clear advice on what to do next, including linking to the person (or people) to email
  • Administrator doesn't need to be capitalized in a sentence
Bad Bad

Your Atlassian OnDemand instance can automatically invite new developers to Bitbucket. When creating a new Atlassian OnDemand user, simply select the Bitbucket group(s) you wish to invite the user to join. Once added to Bitbucket, you can manage your teammates directly from Bitbucket.

Good Good

Add your friends or colleagues to Bitbucket by clicking the button below. Alternatively, let your Atlassian OnDemand instance automatically invite new people to your team.

Improvements explained
  • Replacing 'members' with 'friends or colleagues' or 'people' is more relatable
  • In this case, the user is in the context of Bitbucket. Talk about that first, then the alternative method

Be clear

Make each word, sentence, and paragraph count and spend time crafting your message to perfection. Speak in sentences, not in tiny bursts with many full stops – this comes across as grumpy and short and we don't want that. Less is more, except when less means you're perceived as not having time to care about the user.

Bad Bad

If you would like to manually merge this pull request, execute the following commands:

Good Good

You can manually merge this request by running the following commands:

Improvements explained
  • Eliminate the future tense. In most cases, people use software to perform tasks in the present
Bad Bad

If you want Bamboo to start this plan automatically, you will need to set Triggers to specify how and when the build will be triggered. If you want to start it manually at any time, use the "Run" menu or trigger a release from JIRA.

Good Good

Set triggers for when and how to start this plan automatically. Alternatively, trigger the build from JIRA or use the Run menu to start this plan straight away.

Improvements explained
  • Avoid the use of future tense unless future tense is required
  • The conditional phrasing isn't necessary

Stay harmonious

The language of everything Atlassian should sound like one voice, so look to examples elsewhere to ensure consistency. Avoid difficult to understand technical jargon as much as possible.

Bad Bad

This page allows you to manage all your favourite dashboards.

Good Good

Manage your favorite dashboards on this page.

Improvements explained
  • The page is an inanimate display, it can't allow anything
  • The adjective 'all' is not necessary
  • Use US English
  • A conversational tone is easier to understand
Bad Bad

Conflicts detected:

Good Good

Bitbucket can't automatically merge this request due to these conflicts:

Improvements explained
  • The bad error message doesn't describe the two parts of the problem
  • The brevity of the bad example sounds mechanical. Humans associate mechanical with computers, not friendly people
  • Describe both parts of the problem. 1) Bitbucket cannot merge this request automatically. 2) The reason it failed is due to conflicts

Be helpful

Writing good error messages is tricky. Error dialog titles should be informative yet concise. The message body should explain what happened and instruct the user on how to recover from the error with a clear call to action. Remember to use the other three principles in your error messages.

In the case of destructive actions which result in warnings, be sure to explain to the user exactly what will happen.

Bad Bad

Oops, you've found a dead link

  • Go back to the previous page
  • Go to the Home Page
Good Good

Page not found (404)

This page has gone missing! Search for what you're looking for, or go back to the previous page.

If this keeps happening, perhaps contact an administrator.

Improvements explained
  • Don't use 'Oops' – it's cheesy
  • Convey more information in the title (the error type – 404)
  • Provide useful calls to action
Bad Bad

You aren't allowed to see this. Your project or sys-admin will need to grant you permission.

Good Good

If you think you should have access to Angry Nerds, contact your administrator.

Improvements explained
  • If recovery or troubleshooting isn't possible, provide a message body that points the user to an entity that can help – such as a system admin or Atlassian Support