Author Guidelines

This page contains important information for anyone updating the Atlassian documentation wiki.

In brief:

Please read the Atlassian Contributor License Agreement.
Do not delete, move or rename any page unless you created the page yourself.
Use internal link format rather than the full http://xxxx external link format.
Be aware that the content of some pages is re-used in other pages. Make sure you put your content in the right place.
When updating the Atlassian Plugin Framework documentation in particular, be aware of the extensive content re-use.
Make sure that you update the relevant version of the documentation. We maintain a separate set of documentation for each major version of most applications, as specified in each documentation space name.
Maintain a consistent style, layout, grammar and format as the rest of the page or space.
Use Australian spelling. For example, use 'organisation' not ~~organization~~; use 'customising' not ~~customizing~~.
Use title case for headings, not sentence case. For example, 'This is a Heading'.
Mark all drafts clearly as work in progress.
Please do not edit the release notes, security advisories or policy documents.

The rest of this page contains more detail on each of the above topics.

Atlassian Contributor License Agreement

Please refer to the information and agreement on the ACLA page.

Deleting, Moving or Renaming Pages

Your own pages only
Please do not delete, move or rename any page unless you created the page yourself. Then consider carefully before you delete, move or rename your own pages.

In many of the documentation spaces, only Atlassian staff will have permission to delete a page, comment or attachment. If you need something deleted, please raise a request in the appropriate project on our JIRA issue tracker. For example, if you are requesting a change in the Confluence documentation, raise a request:

in the Confluence project
with issue type = 'Task'
and component = 'Documentation'.

Deleting, moving or renaming a page can be perilous, because:

External sources may refer to the page. For example, the Confluence application itself contains hard-coded links to certain pages in the documentation, especially the online help, README file, or setup wizard. Other applications also have links to the documentation pages.
Page names are included in some Confluence macros, such as the {children} macro and the {include} and {excerpt-include} macros. If you rename, move or delete a page, you may break other pages that contain such macros.

Adding a Hyperlink that Points to Another Page

Please use internal link format rather than the full http://xxxx external link format when linking to another wiki page. This applies to pages in the same space or in another space.

Good	Bad
[My Page Name]	[http://confluence.atlassian.com/display/SPACE/My+Page+Name/]
[OTHERSPACE:My Page Name]	[http://confluence.atlassian.com/display/OTHERSPACE/My+Page+Name/]

Why is internal link format best?

Broken links: You will see immediately if the link is broken. Confluence will colour the link red if the page does not exist.
Automatic update of page name: If someone changes a page name, Confluence will automatically update all internal links.
Space exports: We export documentation to PDF, HTML and XML format, for use by many customers who cannot escape their firewall to access our online documentation. They download the exported files and install the documentation on their own systems. The external links in such offline documentation will link back to the online wiki, instead of linking to the correct page in the downloaded documentation, causing much irritation to the customers.
Release management: Hard-coded links break the release management system we have in place, where documentation for previous versions of each product is held in separate archived spaces.

What is internal link format?

In wiki markup:

Use square brackets plus page name.
Do not include the space key, unless you need to go outside the current space. (Else you will break the documentation release management process.)
To link to a bookmark (anchor), just enter hash (#) plus the anchor name, if you're on the same page. If you're on a different page, add the page name before the #. For example, to link to an anchor called 'details':
```
For details, see the section [above|#details].
```
Use aliases (alternative text) to define the text displayed for your link. In the above example, the word 'above' is an alias.

To go to the home page of a space, type just the space key plus a colon.

What you need to type	What you get
[Author Guidelines]	Author Guidelines
[ALLDOC:Author Guidelines]	Author Guidelines
For details, see the section [above\|#details].	For details, see the section above.
[ALLDOC:]	Atlassian Documentation

Updating Content that is Re-used in Other Pages

Be aware that the content of some pages is re-used in other pages. We use the {include} and {excerpt-include} macros to dynamically copy content from one page into another page, at the time of rendering the page.

Inclusions Libraries

A specific example of content re-use is the pages in our 'Inclusions Libraries', such as the Plugin Framework documentation.

Take a look at the page on the Web Item plugin module. The entire content of this page is included into a page in the Plugin Framework documentation (here) and also in the Confluence documentation space and the Crowd documentation space.

If you want your information to be included in all relevant spaces, put it into the page in the Inclusions Library. If your content is relevant only to one particular space (e.g. Confluence only or Crowd only) then add it to the page in that space.

Updating the Plugin Framework Documentation

Please read the note about content re-use above, because it applies to the Atlassian Plugin Framework documentation in particular.

Documenting the Applicable Version of the Application

Most of our documentation is version-specific. In general, we maintain a separate set of documentation for each major version of each application. When adding or updating documentation, please check the space name and make sure that your update applies to the version specified in the space name.

For each product, there is a current documentation space plus potentially one or more archive documentation spaces holding documentation for earlier versions of the product. For example, the current Crowd documentation is in the CROWD space, and documentation for earlier versions is in CROWD015, CROWD014, etc. Editing of the archive spaces is restricted to Atlassian technical writers. To request an update to such a document, please raise an issue on our JIRA issue tracker, in the project for the relevant product. Set the issue type to 'Task' and the component to 'Documentation'. In isolated cases, we may grant someone edit-permissions for a specific update and then remove the permissions again.

Maintaining a Consistent Style

When you add or update content, please use the same layout, grammar and formatting as the rest of the page or space.

At Atlassian, we pride ourselves on the quality of the documentation. We see it as part of the product. Consistency and correctness of syntax, spelling, punctuation and style contribute significantly to the quality.

Australian Spelling

Atlassian is an Australian company, with customers all over the world. Because we are Australian by origin, we standardise on Australian spelling in our documentation.

Common differences between Australian and US spelling:

When tempted to use a "z", you should probably use an "s" instead. For example:

Good Bad

organisation organization

customising customizing
When tempted to use just one "l", you may need two instead. For example:

Good Bad

travelling traveling

Our reference dictionary is: Macquarie Essential Dictionary, fourth edition, published by Macquarie Dictionary Publishers at the University of Sydney.

Hint: Add an Australian-English dictionary to your browser's spelling checker.

Title Case for Headings

Use title case for headings, not sentence case. For example:

Good	Bad
This is a Heading	This is a heading This Is A Heading
How to Write Atlassian Documentation	How To Write Atlassian Documentation How to write Atlassian documentation

Style Guide

Our style reference is the Style manual for authors, editors and printers, sixth edition, published by John Wiley & Sons Australia, Ltd.

Marking your Drafts as "Work in Progress"

When writing a lengthy piece of documentation, you may need to save the page before you have finished it. Please mark all such drafts or unfinished work, with an information box at the top of the page.

Example:

Work in Progress
This page is a draft. Treat it with caution.

Not Editing Release Notes, Security Advisories and Policy Documents

Please do not edit the following types of documents:

Release notes, such as the Confluence release notes.
Security policy, such as the Confluence security statement.
Security advisories, such as this Confluence security advisory.
Other policy documents, such as the [Confluence Hosted terms of use].

If you feel that something needs changing on a page which falls into one of the above categories, please add a comment to the page rather than editing it. A technical writer will respond to the comment. We are watching the documentation spaces, and will pick up any edits and/or comments as soon as we can.