Language and grammar

Don’t use internal abbreviations in customer-facing copy.

Don’t use apostrophes for plural abbreviations.

Don’t use i.e. or e.g. They are not localization friendly.

• Yes: Jira Service Desk,  jira.atlassian.com, developer.atlassian.com

• No: JSD, JAC, DAC, CD’s, 1980’s, i.e., e.g.

• Yes: Administrators control user access to Atlassian Cloud applications.

• No: User access to Atlassian Cloud applications is controlled by administrators.

Use bold text to draw the reader’s eye to key phrases and statements in your email and web content. For product copy or help articles, use bold for static UI elements like menu items, buttons, screen headings, and anything else you want to call attention to.

If you need to bold an element but the UI doesn’t support it, for example, in a dialog header or a UI message, you can use italics instead.

Use italics for fields that might change, like a page name. See italics for more guidelines.

• Yes: Go to General Configuration > User Macros.

• No: Go to the settings page and select Configuration.

Use sentence case in all titles, headings, menu items, labels, and buttons.

• Yes: This is the new Jira experience!

• No: This Is The New JIRA Experience!

• Double no: tHiS iS tHe nEw JIRA eXpErIeNcE!

Use colons to introduce a bulleted list or series of steps. Don’t use colons at the end of headings.

In keeping with our more conversational, friendly voice, use contractions.

Use curly apostrophes wherever possible in UI copy by typing option+shift+] on a Mac.

• Yes: Can’t, don’t, it’s

• No: Cannot, can not, it is, it's (not curly)

Use em dashes sparingly to indicate an abrupt or dramatic change in a sentence — like this. lf the break happens in the middle of a sentence — like this — use em dashes on either side of the phrase.

Em dashes can help avoid confusion when the phrase being set apart contains several commas, such as a mid-sentence list. In general, though, try to keep sentences as short and simple as possible to avoid excessively complex punctuation.

Use spaces on either side of an em dash. Use option-shift-hyphen to make an em dash on a Mac.

For ranges of numbers, use a hyphen with no spaces — not an em or en dash.

• Yes: The newly released Jira 6 — our best Jira yet — will be available next week.

• No: The newly released Jira 6—our best Jira yet—will be available next week.

• Yes: He said his friends — Mike, Charlie, and Scott — would be arriving late. They should arrive anywhere from 2-4.

• No: He said his friends - Mike, Charlie, and Scott - would be arriving late. They should arrive anywhere from 2—4.

See Date and time guidelines.

Quote with curly quotes, not italics. See Quotation marks for details.

• Yes: “Jira Software is the best software ever!” said Charlie.

• No: Jira Software is just ok. said Charlie.

Don’t put spaces in-between the periods in an ellipsis. When using an ellipsis to omit part of a long quote, include spaces on either side of the ellipsis ( ... ).

• Yes: “From medicine and space travel, to disaster response ... our products help teams all over the planet advance humanity through the power of software.” Atlassian: Discover our story.

Ellipses sometimes show that text was cut off or truncated when a message doesn’t fit in the given space. Avoid truncation whenever possible using these techniques:

• Shorten UI messages and front-load important information.

• Wrap the text or use other techniques instead of truncating.

Test your designs using multiple screen widths and magnification levels to ensure it doesn’t truncate.

When you can’t avoid truncation, provide an alternative way to view the full text for accessibility and usability.

In Atlassian Design System components that truncate, the ellipsis appears without any space next to the last visible character (for example, Sign up for...).

• Yes: This message is trunca…

Avoid exclamation marks! They should only be used for exciting or new things! At most, there should only be one exclamation mark per page!

When possible, avoid gendered pronouns. If you can’t, then they or their is preferable to his or her or he or she.

• Yes: Ask your admin to add you.

• Yes: Ask your admin if they can add you.

• No: Ask your admin if he or she can add you.

Use hyphens to form a single idea from multiple words. In general, only use hyphens when they help to avoid confusion or ambiguity.

When two or more words function together as a descriptor or adjective (also known as a compound modifier), we typically hyphenate those words if they precede the noun they describe, but don’t hyphenate if they come after the noun. There are exceptions to this rule, such as with the word very or any adverbs ending in -ly.

• Yes: Fast-moving trucks, ice-cold drinks, dog-friendly hotels. The hotel is dog friendly.

• No: Very-interesting topics, poorly-worded sentences.

Most prefixes don’t require hyphens to be understood. Only use a hyphen if not doing so causes confusion or ambiguity. Consult a modern dictionary to be sure.

• Yes: Autocorrect, coworker, and preexisting are all fine without a hyphen. Recreating in a park, however, is different from re-creating a page. I could resign from my job one day, then re-sign my contract the next.

• No: Avoid creating nonsense words by when using prefixes without hyphens, such as nonlife in nonlife-threatening.

Use hyphens for number ranges with no spaces on either side. For example, see rows 1-4 in the table.

There are always exceptions, and some commonly hyphenated words can become closed over time (remember e-mail?). Check Vocabulary for more specific hyphenated word guidance.

Use italics for emphasis, citations, or defining a term. You can also use it for UI elements that might change, like a field name or user input.

You can also use italics in places where you would normally use bold but the UI doesn’t support it. For example, in a dialog header or UI message.

Don’t use italics if the item is also a hyperlink.

See bold for more information about how to format UI elements.

• Yes: A JIRA workflow is the set of statuses and transitions that an issue goes through during its lifecycle.

• Yes: According to the 2008 IT Unplugged report, IT is really unplugged!

• Yes: For example, if you create a metric called Time to resolution, other projects can create metrics with that name.

• No: To learn more, see the 2008 IT Unplugged report

• No: In your project, select Settings>Request types

Use lists to draw the reader’s eye and make items easier to scan and follow. Use proper punctuation in your items if they are complete sentences. Try to limit lists to six items or less. If you need more items, see if you can split the list into multiple lists.

Use bulleted lists for options, or a list where the order of the items doesn’t matter. Phrase each item in a parallel way. If the bullets complete the introductory sentence, start the fragments with lowercase and skip the periods.

Yes:

Due to security concerns, all employees are now required to:

• wear an identification tag in the building

• identify themselves when answering the phone

• use their identification tag to enter or leave before 7 AM and after 6 PM

• alert security if a suspicious package is found

No:

Due to security concerns, all employees are now required to follow the regulations below:

• Wear an identification tag when in the company building

• Employees who answer the phone must first identify themselves

• Entering the building before 7 AM and after 6 PM requires that employees use their identification tag to enter or leave the building

• When opening all packages, alert security if the package is suspicious.

Use numbered lists for tasks, or lists where the order of the items matters. Unlike with bulleted lists, always capitalize the first word in each item and end the item with a period.

You don’t need to create a list for tasks that have two or fewer steps.

To add a new user macro:

1. Go to Settings > General Configuration > User Macros.

2. Choose Create a User Macro.

3. Enter the macro details.

Use monospaced font for names of a file or directory. It is mostly used in administrator and developer docs. For example:

The location of the Home directory is stored in a configuration file called confluence-init.properties which is located in the confluence/WEB-INF/classes directory in your Confluence Installation directory.

Write out numbers one through ten. After ten, you can use 11, 12, 108, and so on.

Can’t remember if it’s filesystem or file system? Check out our Vocabulary.

Use the Oxford or serial comma to offset the final item in a list.

• Yes: We use sentence case in all titles, headings, menu items, and buttons.

• No: We use sentence case in all titles, headings, menu items and buttons.

Use a period at the end of complete sentences, including in the description text of products, messages, and notifications. Add only one space after a period.

This includes sentences where the link is part of the sentence. Don’t hyperlink the period.

• Yes: Atlassian’s work is guided by five core values.

• No: Atlassian’s work is guided by five core values

Don’t use periods in headers, titles, tooltips, field descriptions, and menu names, even if they are full sentences.

Only use periods in a bulleted list if the list item is a complete sentence. Don’t add a period at the end of a list of fragments.

Use ’s to show possession, even if the word ends in s. Use curly apostrophes by typing option+shift+] on Mac.

• Yes: James’s book

• Yes: a week’s time

• No: James' book

In most cases, second person is best. It fits Atlassian’s casual, conversational tone to refer to the reader directly with you. Exceptions can be made for specific types of writing, such as whitepapers and press releases.

Not sure whether it’s My projects or Your projects? For best results, avoid using mine, my, or your in UI copy.

If you need to use mine, my, or your, the rule of thumb is to think of the UI as a conversation between the system and the user.

If the system is presenting information to the user, such as in a dialog box, then your is more appropriate, because it’s like saying “Here are your things”, or “What would you like to do?” If the user is performing an action, such as clicking a button or a link, then mine/my is more appropriate, because it’s like saying “Show me my stuff!”

• Yes: Bitbucket will change your life.

• Yes: Your team will love using pull requests in Bitbucket.

• No: Teams love using pull requests in Bitbucket.

Use double quotes (“”) for direct quotes. For UI elements, page titles, and other objects, use bold or italicized text as appropriate.

Use curly quotes in any UI or body copy, unless you're writing in code or there is a semantic reason to use straight quotes. To create curly quotation marks, use option+[ for opening and option+shift+[ for closing quotation marks on a Mac.

Punctuation goes inside the quotation marks.

• Yes: “We have big things planned for the coming year,” said Mike and Scott.

• Yes: He called quokkas “the cutest animal ever.”

• No: Add a comment to the "Team processes" page.

• No: The shark said "Surfers are delicious".

Five great guidelines for clear, concise writing, courtesy of George Orwell:

1. Don’t use a metaphor, simile, or other figures of speech that you commonly see.

2. Don’t use a long word if a shorter one will do.

3. If you can omit a word, do it.

4. Use active voice.

5. Don’t use foreign phrases, scientific nomenclature, or jargon if there's an everyday word you can use instead.

Use sentence case. Don’t use bold, italics, or standard punctuation in headings. It's ok to use question marks and exclamation points if they fit the criteria for those two marvelous pieces of punctuation.

• Capitalize the first word of a title or heading (sentence case)

• Capitalize proper nouns and any trademarked names (products, countries, people's names, etc...)

• Don’t use full stops

The use of articles (the, a, an) in headings depends on whether the message is conversational or action-based microcopy. Avoid articles in buttons and labels.

In more conversational sections of the interface, like Home cards, marketing copy, and empty states, use articles. It makes the language more approachable and helps understanding when introducing new, complex concepts.

Phrase documentation H1s with an action verb. Using action verbs informs the user of the type of content they can expect to find (for example, Learn versus Get). Don’t use gerunds.

• Yes: Create a page

• No: Creating a page

More documentation guidelines for Atlassian employees (login required).

• Use sentence case, even if the UI element does not

• Use bold to call out the UI element in a step. Don’t bold the >.

• If the UI element has an icon, use both the name and the icon.

Go to More ••• > Link issues.

We write with US English spelling and punctuation, but our Australian roots are still part of our personality. Communications from Australians can use Australian English such as colour, optimise, theatre.

For example, Aussie PMs writing JAC comments to customers can use Australian English. Developers should code in US English.

• Yes: What kind of cookie would you like with your coffee, friend?

• No: Which biscuit do ya want with your cuppa, mate?

Follow the AP Style Guide.