Content voice and tone

Introduction

Why do we need a style guide?

The style guide is here to help you write with precision, while maintaining personality and authenticity, so our audiences will engage with us.

The Atlassian ecosystem is growing quickly, with hundreds of developers building add-ons. The people add-on developers are speaking to – via in-product copy, help docs, and the Atlassian Marketplace – have thousands of bits of media vying for their attention every day. In order to get through, your copywriting must be relevant, consistent, authentic, and engaging.

Who is this guide for?

Add-on developers who want their in-product and Marketplace copy to have that "Atlassian feel".

How to use this guide

  • Bookmark for future reference.
  • Read the whole thing, or use the table of content to the left tor find your issue topic.
  • Understand that this is a living document.

Best practices

  • Content
    • Short, direct, and pithy is better than (and outperforms) long and granular. Write for busy people with short attention spans.
    • Never use a long word where a short one will do. (Example: Don't say breviloquent when you can just say short.)
  Examples
  • Bad: "We're excited to announce the heavily anticipated release of Atlassian's Bamboo 5!"
  • Good: "Bamboo 5 is here!"
  • Active voice… mostly
    • To write in active voice, make sure that the subject of your sentence is doing the action. ("She ran to the park" instead of "The park was where she ran to.") In passive voice, the target of the action gets promoted to subject status.
    • Passive voice has its uses, but save it for content written in a narrative style – and even then, use it sparingly.
  Examples
  • In the sentence "Giancarlo wrote the blog post," Giancarlo is the subject, and he is doing the action. The object of the sentence is the blog post, and it's having an action done to it: it's being written.
  • This same sentence in passive voice would be "The blog post was written by Giancarlo." Even though Giancarlo is the one doing the writing, the focus of the sentence has switched to the blog post.
  • First, second, or third person?
    • In most cases, using the second person is preferable. It fits Atlassian's casual, conversational tone to refer to the reader directly.
      • Exceptions can be made for specific types of writing, such as whitepapers and press releases.
      • The concept of teams is central to our branding. Whenever possible, use "your team" instead of simply "teams" – it's far more personal.
  Examples
  • Good: Bitbucket will change your life.
  • Good: Your team will love using pull requests in Bitbucket.
  • Bad: Teams love using pull requests in Bitbucket.

Brand and voice

Why it's important

Atlassian has a unique public voice. It's refreshing. It's a big part of what separates us from the herd of humdrum B2B vendors. And it's a big part of why customers (both present and future) love us.

In other words, it's a strategic asset.

By infusing this voice into modal dialogs, error messages, etc., your add-on will feel more like an organic part of the product and provide a better experience for your users.

Voice vs. tone

Voice is your personality, tone is your mood.

This means that the characteristics of our voice will remain constant, while our tone will change depending on the situation. Imagine you're a word DJ. (Go on, imagine it.) You've got your mixer in front of you with knobs and sliders you can tweak to create whatever effect your audience needs at the moment. There are knobs for bold, optimistic, and practical with a wink.

Here's how to adjust your levels.

Writing copy in (and about) your add-on

Blank slate

What it's for: A blank slate message is used when an area doesn't have any content.

It's waiting on the user to take an action, and is often a first experience.

Your job: Communicate possibility.

What they will see? What they can do? How this will help them get stuff done?

Users should feel...

  • Curious
  • Motivated
  • Empowered

Quick tips

  • Be welcoming
  • Have a call to action
  • Communicate a benefit
reserved ----------------------------------------- bold
neutral ----------------------------------------- optimistic
factual ----------------------------------------- playful
  Examples

Spot on

(Bitbucket)
(Confluence)

Empty state

What it's for: When an area that usually displays content is temporarily empty.

Typically (though not always), it means the user has completed whatever work normally appears in that space.

Your job: Explain why the area is empty.

What's happened, what will appear here, and how it'll get there.

Users should feel...

  • Pleased
  • Informed
  • Reassured

Quick tips

  • Be reassuring
  • Explain what, why, when
  • If appropriate, celebrate!
reserved ----------------------------------------- bold
neutral ----------------------------------------- optimistic
factual ----------------------------------------- playful
  Examples

Spot on

(Confluence)
(Jira Service Desk)

Alert

What it's for: Communicating new information.

Especially information that may affect the user's next action.

Your job: Update the user about what happened.

Let them know how it affects them, and then let them get back to work. You can be fun, but not super chatty.

Users should feel...

  • Informed
  • Helped
  • Empowered

Quick tips

  • Be clear
  • Be concise
  • Say why its important
reserved ----------------------------------------- bold
neutral ----------------------------------------- optimistic
factual ----------------------------------------- playful
  Examples

Spot on

(Confluence)
(Hipchat)

Error message

What it's for: When something has gone wrong.

It often means a dead-end for the user.

Your job: Explain the problem and provide next steps.

Don't baffle users with technical detail, keep it simple and direct. If it's our fault, own up. If it's user error, don't belittle them.

Users should feel...

  • Supported
  • Reassured
  • In control

Quick tips

  • Be clear
  • Explain the cause
  • Provide an alternative
reserved ----------------------------------------- bold
neutral ----------------------------------------- optimistic
factual ----------------------------------------- playful
  Examples

Spot on

(Confluence)
(Confluence)

Feature discovery dialog

What it's for: Highlighting a new or recently updated feature.

It's all about user engagement in the product. Which is all about MAU.

And we're all about MAU.

Your job: Be persuasive.

Let the user know what's changed and invite and entice them to try something new.

Users should feel...

  • Curious
  • Excited
  • Empowered

Quick tips

  • Introduce the change
  • Communicate a benefit
  • Provide a call to action
reserved ----------------------------------------- bold
neutral ----------------------------------------- optimistic
factual ----------------------------------------- playful
  Examples

Spot on

(Confluence)
(Team Calendars)

Form

What it's for: Getting the user to enter data or configure options.

Forms can be long or short.

Your job: Help the user succeed.

Make their path clear and simple. Skip the long explanations — use good examples and placeholders instead.

Users should feel...

  • Supported
  • Encouraged
  • Eager

Quick tips

  • Be helpful
  • Guide the user
  • Give examples
reserved ----------------------------------------- bold
neutral ----------------------------------------- optimistic
factual ----------------------------------------- playful
  Examples

Spot on

(Confluence)
(Confluence Questions)

Warning

What it's for: Preventing error situations.

Help the user course-correct before things go wrong.

Your job: Inform, without alarming the user.

Clearly communicate the consequences of proceeding, and provide an alternative action (if there is one).

Users should feel...

  • Informed
  • Supported
  • Reassured

Quick tips

  • Be clear
  • Explain the situation
  • Provide an alternative
reserved ----------------------------------------- bold
neutral ----------------------------------------- optimistic
factual ----------------------------------------- playful
  Examples

Spot on

(Confluence)

Marketplace page

What it's for: Telling prospective customer's why your add-on is so awesome.

Add-on pages with rich descriptions get more sales! But don't go overboard — customers don't have time to read a novel.

Your job: Tell a compelling story.

How will your add-on help their team work smarter? Focus on benefits to the user, rather than just describing features.

Users should feel...

  • Informed
  • Eager
  • Delighted

Quick tips

  • Focus on how users will benefit, rat
  • Go easy on the exclamation points
  • Don't over-promise
reserved ----------------------------------------- bold
neutral ----------------------------------------- optimistic
factual ----------------------------------------- playful
  Examples

Spot on

(From Balsamiq — Great job selling it, without over-promising. Copy is dynamic, and the middle section is especially focused on benefits to the user.)

Room for improvement

(From Zephyr — Inconsistent capitalization in the headlines doesn't make an awesome first impression. We prefer sentence case, like the "Test right inside Jira" headline.)

Other communications

Help docs

What it's for: Showing users how to get $#!t done using your add-on.

Technical documentation has to be clear and specific. It does not, however, have to be boring.

Your job: Get the user back into the product.

Give "just enough" info to help them understand the use case and perform the operation.

Users should feel...

  • Empowered
  • Relieved
  • Delighted

Quick tips

  • Keep it casual
  • Represent diversity in examples/screenshots
  • Just the facts, ma'am... just the facts
reserved ----------------------------------------- bold
neutral ----------------------------------------- optimistic
factual ----------------------------------------- playful
  Examples

Spot on

(From the Confluence docs — Very informative, yet casual. Using "you're" instead of "you are" and phrases like "those really long tables" contribute to the friendly, informal vibe.)
(From the Confluence docs — Provides some context around this operation, but doesn't go into an exhaustive list of reasons why you'd want to move a page.)

Room for improvement

(From the Confluence docs — Good representation of gender diversity, but the names are noticeably Euro-centric.)
(From the Jira docs — Informative, but really stiff. "We recommend" instead of "it is recommended" and "make sure X because Y" instead of "ensure X as Y" would be friendlier.)

Release notes

What it's for: Communicating what's changed in your add-on's latest release.

Tout the shiny new features, plus provide the essential info that'll impact an admin's decision to upgrade.

Your job: Drive adoption.

Get users excited about shiny new features, and help them feel confident about upgrading.

Users should feel...

  • Eager
  • Informed
  • Connected

Quick tips

  • Think about how each feature benefits a team
  • Have a little fun
  • Give admins the 'full story" so they can upgrade with confidence
reserved ----------------------------------------- bold
neutral ----------------------------------------- optimistic
factual ----------------------------------------- playful
  Examples

Spot on

(From CAC — It is indeed with "great pleasure" that we ship new releases. Go ahead and let that show!)
(From the Confluence 5.8 release notes — Phrases like "a real drag," "automagically" and "mammoth tables" make this section delightful to read.)

Room for improvement

(From the Jira 4.4 release notes — There's no real flow between sentences and no narrative, which makes it hard for the reader to get excited. And the screenshot of an issue titled "Crappy initial experience" is rather un-optimistic.)