Style guide: content, voice, and tone
This style guide is here to help you write with precision, while maintaining personality and authenticity, so your audiences will engage with you. In other words, it will help your add that "Atlassian feel" to your marketing.
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.
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.)
- Bad: "We're excited to announce the heavily anticipated release of Atlassian's Bamboo 5!"
- Good: "Bamboo 5 is here!"
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.
- 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, and 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.
- Bad: Teams love using pull requests in Bitbucket.
- Good: Your team will love using pull requests in Bitbucket.
Video: "Nailing the Atlassian Voice in Your Add-on"
Check out this video to learn more about Atlassian's approach to voice and tone in your content.