Skip to end of metadata
Go to start of metadata

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

In brief:

  1. Please read the Atlassian Contributor License Agreement.
  2. Do not delete, move or rename any page unless you created the page yourself.
  3. Use internal link format rather than the full http://xxxx external link format.
  4. Be aware that the content of some pages is re-used in other pages. Make sure you put your content in the right place.
  5. When updating the Atlassian Plugin Framework documentation in particular, be aware of the extensive content re-use.
  6. 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.
  7. Maintain a consistent style, layout, grammar and format as the rest of the page or space.
    1. Use Australian spelling. For example, use 'organisation' not organization; use 'customising' not customizing.
    2. Use title case for headings, not sentence case. For example, 'This is a Heading'.
  8. Mark all drafts clearly as work in progress.
  9. Please do not edit the release notes, security advisories or policy documents.
  10. Please read these detailed style guidelines.

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

1. Atlassian Contributor License Agreement

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

2. Deleting, Moving or Renaming Pages

Your own pages only

Icon

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:

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.

3. Adding a Hyperlink that Points to Another Page

Please use relative (internal link) rather than absolute (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. Refer to Working with Links for details.

Good (tick)

Bad (error)

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.

 

4. 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 User Management inclusions library. Take a look at the page about nested groups. The entire content of this page is included into a page in the Confluence documentation (here) and also in the JIRA documentation (here).

Icon

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.

5. 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.

6. Document 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.

7. Maintain 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:

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

    Good (tick)

    Bad (error)

    organisation

    organization

    customising

    customizing

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

    Good (tick)

    Bad (error)

    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 (tick)

Bad (error)

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.

8. Mark 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

Icon

This page is a draft. Treat it with caution.

9. Don't Edit Release Notes, Security Advisories and Policy Documents

Please do not edit the following types of documents:

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.

10. Documentation Style Guidelines

General Page Structure Guidelines

  • Page name: Most pages should start with a gerund (e.g. "Adding a user").
  • Introduction: Write an introduction that provides useful context, i.e. why a reader would use the function, not just what it is.
  • Content: Limit page content to one major topic per page, where possible.
  • Table of contents: Use a table of contents, if there is more than one header (other than Notes) on the page. Include h2 to h4 only. Position the table in the top right of the page in a panel titled 'On this page'.
  • Pre-requisites: List pre-requisites in a 'Before you begin' bulleted list before the procedure. If the pre-requisites apply to more than one procedure on the page, create a new section for it after the introduction.
  • Procedure: Describe the procedure in numbered steps in a new section.
  • Screenshots/Diagrams: Display screenshots/diagrams after the text that it is related to.
  • Next Steps: If the page leads logically to another page, include a 'Next Steps' section containing the appropriate link(s).
  • Notes: If a note does not need to be displayed next to a particular step/point, list it in a 'Notes' section at the end of the page. If you need to warn a customer about a critical issue, add it after the introduction. Avoid using too many coloured panels.
  • Related pages: Add links to relevant related pages in a 'Related Topics' section at the end of the page (don't just add a children macro). Precede it by a horizontal rule and the words 'Related topics' (bold; not a heading).
  • Labels: Add labels. Search for existing labels before creating new ones.

Example:  Defining Plan Variables

Typographical Conventions Guidelines

  • Heading hierarchy: Start with H2 and go down in sequence. If your page is short, there is no need for a heading.
  • Capitalisation: For existing products, in headings and page names, use title case (Capitalising All the Big Words) rather than sentence case (Capitalising only the first letter). For new products and new spaces, use sentence case. In other text, capitalise only the first letter of proper nouns. Use lower case for the names of features or concepts used in the application, such as screen and issue (JIRA), page and comment (Confluence), plan (Bamboo), etc.
  • Quotation marks: Use single quotes rather than double.
  • Emboldening: Use bold text selectively, because bold text is used in UI elements.
  • Referring to UI elements: Use bold text.
  • Emphasis: Use italics only.
  • Warnings, notes and other boxes: Avoid colourful boxes. People don't read them.
  • Code snippets: Use the code macro for block-level snippets. Use monospace formatting for inline snippets.
  • General style: Do not override the colours, fonts and text styles provided by the Documentation Theme (or whatever theme your space is using.)
  • Lists: Use numbered lists for instructions, and only for instructions. Use bulleted lists for other lists. Do not use a list if there is only one item in it.
  • Spelling: Use Australian English.

When in doubt, consult our style reference guide:  the Style manual for authors, editors and printers, sixth edition, published by John Wiley & Sons Australia, Ltd.

Example: Managing Nested Groups

Task Description Guidelines

  • Some pages might encompass multiple sub-tasks that make up a larger task. If so, use numbered headings for each sub-task.
  • Use numbered steps (ie. a numbered list) for each task (or sub-task).
  • Use '>' to keep instructions as brief as possible.
  • Omit the obvious (e.g. "Click the OK button").
  • Where possible, reference instructions and/or screenshots on the same page (though not on other pages), rather than reproduce the same steps multiple times. E.g. "Go to the 'Custom Fields' screen as described [above]"
  • Document complex, important or non-obvious fields in detail. Consider omitting documentation for obvious fields, especially optional ones (such as the Description field on many admin screens in JIRA).
  • Only describe input for specific fields on the screen where needed. If you need to describe multiple fields and cannot get the text added to the UI, describe it in the procedure using a table (> 3 items) or bulleted list (< 3 items)
  • If you need to document lots of complex, important or non-obvious fields, use a table.

Example:

To add a repository:

  1. Select Admin > Repository List > Add repository.
  2. Select a Repository type from the dropdown list.
  3. Specific fields will appear on the 'Add Repository' screen, depending on the chosen repository type. Enter the repository details as prompted. You will find more information in the specific sections listed below.


Screenshot Guidelines

  • Usage: Only use screenshots when you really need them as a "location anchor" for users, but not for every point in a series of steps.
  • Format: Save screenshots in PNG format.
  • Screenshot size:Capture screenshots and present them on the page at their full-size. However, if they are bigger than 700px wide, reduce their size in Confluence to 700px.
    • Avoid altering their size in an image editor — let Confluence do the shrinking (if it's required), since when viewing the page, you can always click the image to view its full size.
    • For Gallery Macro: To be determined by Analytics stats on usage of printed versions.
  • Border: Add a Confluence border around each screenshot.
  • Edge effects: Use the Snagit fading effect when available.
  • Anti-aliasing: Ensure that any area of screenshot you are capturing is anti-aliased. On Windows operating systems, this usually entails ensuring that ClearType has been activated in your Display Settings.
  • Only include necessary detail: When taking screenshots, omit any unnecessary detail. Only include the area of the page (or menu items) applicable to the context described in your documentation.
  • Captions: Place captions above screenshots in italicised text. Unless a screenshot description is absolutely necessary, do not use captions on screenshots incorporated into procedural steps.
  • Indenting screenshots: Screenshots should not be indented (i.e. appear flush against the left of a page) unless they are part of procedural steps, in which case, use Confluence's Ctrl+Enter feature to ensure they are indented to the correct step level.
  • Annotations: Use Gliffy. Don't use Snagit effects (except edge fading).

 

Diagram Guidelines

  • Create diagrams in Gliffy, using Gliffy's default shapes and colours. [TEMPLATE PENDING ].
  • Consider a horizontal orientation wherever possible.
  • Diagram width should be 700px. This may influence your choice of vertical/horizontal orientation.
  • Use as few words as possible.
  • Use sentence case for text within boxes.
  • Wherever possible, link words to relevant pages for further information.
  • Conceptual diagrams:
    • [TEMPLATE TBA]
  • Flowcharts:
    • [TEMPLATE TBA]
    • Represent objects (nouns) as boxes.
    • Use verbs to label arrows, if labels are necessary (e.g. don't label an arrow if it simply indicates a flow from one box to the next).
    • Use diamonds to represent decision points in flowcharts, or to label arrows where more words are needed than will fit nicely with (or within) an arrow.
    • Ensure that for each pair of consecutive boxes: the text in the first box, plus the text in the connecting arrow, plus the text in the second box, makes sense when read in isolation.

Example: http://confluence.atlassian.com/display/JIRA/People+and+Permissions


Progress Trackers Guidelines

Read more: Progress Trackers in Web Design Best Practices.

  • Use Gliffy, but don't use the Gliffy default colours and shading [TEMPLATE UNDER DEVELOPMENT].
  • Use sentence case for text within boxes.
  • Use numbers on the names of each step to emphasise their sequential nature.
  • The navigation link to the current page should be highlighted and not-clickable.
  • Navigation links to other pages should be visible and readily clickable.
  • Consider a (smaller) progress tracker — or Next/Previous buttons — at the bottom of long pages, to save the user scrolling up and down.

Related Topics

Contributing to the Atlassian Documentation

  • No labels

0 Comments