Direct quotes
Quote with quotes, not italics.
-
-
- Yes : "Jira Software is the best software ever!" said Charlie. -
- No: Jira Software is just ok. said Charlie. +
- Yes : "I2P is the best software ever!" said Mike. +
- No: I2P is just ok. said Mike.
Exclamation marks
Avoid exclamation marks! They should only be used for exciting or new things! At the most, there should only be one exclamation mark per page!
Gender
When possible, avoid gendered pronouns. If you can't, then they or their is preferable to his or her or he or she.
-
-
- Much yes: Ask your admin to add you to the instance. -
- Yes: Ask your admin if they can add you to the instance. -
- No: Ask your admin if he or she can add you to the instance. +
- Much yes: Ask your mentor to show you around the router console. +
- Yes:Ask your mentor if they can show you around the router console. +
- No: Ask your mentor if he or she can add you to the instance.
Hyphens
-Not sure if it's coworker or co-worker? See the Word List (coming soon!)
Instructions
Use different verbs depending on what you're telling the user to do:
Yes:
-
-
- Choose: the user is picking from one of several options, such as in a dropdown +
- Choose: the user is picking from one of several option
- Select or click: the user is clicking or tapping something -
- Tap, swipe: these are okay on mobile -
- Go to, head to: okay for the first item in a menu cascade +
- Tap, swipe: these are tailored for mobile +
- Go to, head to: okay for the first item in a menu
- Hit @@ -88,15 +87,15 @@
- 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. +
- No: To learn more, see the I2P Documentation. +
- No: In the Router Console, select Addressbook > Contact.
Lists
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 fewer. If you need more items, see if you can split the list into multiple lists.
Bulleted
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:
+Due to security concerns, everyone is now required to:
- wear an identification tag in the building
- identify themselves when answering the phone @@ -104,7 +103,7 @@
- alert security if a suspicious package is found
No:
-Due to security concerns, all employees are now required to follow the regulations below:
+Due to security concerns, everyone is 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 @@ -117,16 +116,11 @@
- Go to
> General Configuration > User Macros.
- - Choose Create a User Macro. -
- Enter the macro details. +
- Choose Create a User Persona. +
- Enter the persona details.
- No: James' book
- Yes: Bitbucket will change your life. -
- Yes: Your team will love using pull requests in Bitbucket. -
- No : Teams love using pull requests in Bitbucket. +
- Yes: I2P will change your life. +
- Yes: Your team will like using I2P. +
- No : People like using I2P.
- Don't use foreign phrases, scientific nomenclature, or jargon if there's an everyday word you can use instead.
- Capitalize the first word of a title or heading (sentence case)
- Capitalize proper nouns and any trademarked names (products, countries, people's names, etc...) @@ -200,13 +194,8 @@
- Yes: What kind of cookie would you like with your coffee, friend?
- No: Which biscuit do ya want with your cuppa, mate?
To add a new user macro:
Monospaced text
-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.
Numbers
+<Numbers
Write out numbers one through ten. After ten, you can use 11, 12, 108, and so on.
-One word or two?
-Can't remember if it's filesystem or file system? Check out the Word List (coming soon!)
Oxford comma
Use the Oxford or serial comma to offset the final item in a list.
-
@@ -147,14 +141,14 @@
Pronouns
-In most cases, second person is best. 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.
-Not sure whether it's My projects or Your projects? It can be fuzzy, so sometimes, we aren't either! For best results, avoid using mine, my, or your in UI copy.
+In most cases, second person is best. 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!".
-
-
Quotation marks
Use double quotes (") for a direct quote. For UI elements, page titles, and other objects, use bold text or italics as appropriate.
@@ -175,7 +169,7 @@Titles and headings
-Use sentence case for 
. 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.
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.
Go to More ••• > Link issues.
US English
-We write with US English spelling and punctuation, but our Australian roots are still part of our personality. Communications directly from native Aussies can use the Queen's English – e.g., colour, optimise, theatre.
-For example, Aussie PMs writing JAC comments to customers can use Australian English. Developers should code in US English.
+We write with US English spelling and punctuation. Developers should code in US English.
When all else fails
-We follow the AP Style Guide.
- -