How JIRA Documentation Updates are Published

Still need help?

The Atlassian Community is here for you.

Ask the community

Documentation is organised by major product version

As you can see from this web site, Atlassian's technical writers use Confluence to prepare and publish documentation for Atlassian's products.

The documentation for each major version of JIRA is housed in its own Confluence space. Examples of major versions of JIRA are '4.3.x', '4.4.x' or '5.0.x', where 'x' represents a minor version/release number. Any documentation relating to specific features in minor versions/releases of a major JIRA version are also housed in the documentation space for that major version.

While the names of spaces can be changed in Confluence, each space is identified by a unique 'space key', which remains static.

(tick) When viewing a Confluence page, the 'space key' of the space to which the page belongs can be found immediately after the display/ part of that Confluence page's URL.

Traditional documentation publishing process

(warning) This process is no longer being employed to publish JIRA documentation updates. All version numbers mentioned in this section are used solely for demonstrating this process and do not reflect our current online JIRA documentation.

Documentation for the latest official major version of JIRA (for example, JIRA 4.2.x) is housed in the Confluence space on this site with the 'JIRA' space key.

Documentation updates for the next major version of JIRA (for example, JIRA 4.3.0) are drafted in this same Confluence space (with the 'JIRA' space key). Each draft page created is hidden from public view by applying page viewing restrictions.

Just prior to the release of the next major version of JIRA, we begin 'branching' the documentation.

This documentation 'branching' process involves the following steps:

  1. We create a copy of the 'JIRA' space on this site using Confluence's 'Copy Space' plugin. The copied space is given a space key which reflects the latest official major version of JIRA, based on the format 'JIRA0XY' (where X and Y reflect the first two numbers that constitute this major version of JIRA).
    (info) Documentation in the new 'JIRA0XY' space, which is initially hidden from public view via space permissions, will apply to the previous major version of JIRA once the next major version of JIRA is officially released.

  2. Immediately after the next major version of JIRA is officially released, we perform the following sub-steps:

    1. The 'JIRA' space is renamed to reflect the new latest official major version of JIRA, for example, 'JIRA 4.3'.

    2. The 'JIRA0XY' space (for example, 'JIRA042') is revealed to the public by adjusting space permissions and we ensure it is renamed to reflect the previous major version of JIRA, for example, 'JIRA 4.2'.

    3. We publish the drafted content for what is now the new latest official major version of JIRA in the 'JIRA' space.

(tick) For more information about this process, please refer to 'From draft to published document' and 'Documentation Release Management' in our blog series on 'Technical Writing in a Wiki'.

Recent documentation publishing process

Since the release of JIRA 4.3.0, we have modified the traditional documentation publishing process above.

Instead of waiting until the next major version of JIRA is officially released, we begin the 'branching' steps (above) earlier during development of the next major version of JIRA. For the release of:

  • JIRA 4.3.0 — we performed the branching steps just prior to the release of JIRA 4.3 Beta 1 and at sub-step 2a, the 'JIRA' space was renamed 'JIRA 4.3 Beta'.
  • JIRA 4.4.0 — we performed the branching even earlier (just prior to the release of JIRA 4.4 EAP 2) and at sub-step 2a, the 'JIRA' space was renamed 'JIRA 4.4 EAP'.
    • When JIRA 4.4 Beta 1 was released, we performed sub-step 2a again, by renaming the 'JIRA' space 'JIRA 4.4 Beta'.

Implications of this new process

Branching our documentation early during early development of the next major version of JIRA has the following implications:

  • A dedicated documentation space for the latest official major version of JIRA becomes available. For instance, the 'JIRA 4.3' documentation space (with space key 'JIRA043') became available when JIRA 4.4 EAP 2 was released.
  • The 'JIRA' space reflects JIRA documentation for the next major version of JIRA. For instance, the 'JIRA 4.4 EAP' documentation (with space key 'JIRA') became available when JIRA 4.4 EAP 2 was released.

Customers searching our documentation via Google may find that their Google search results selectively choose pages in the 'JIRA' space for the next major version of JIRA, as mentioned in JRA-24805.

Why have we adopted this new process?

Branching our documentation early offers the following important benefits:

  • Customers who wish to try out early versions of the next major version of JIRA, as well as developers who wish to update their JIRA plugins for compatibility with that JIRA version will have access to documentation for that JIRA version (if available).
  • Publishing documentation updates is easier since we work with live content in documentation spaces with 'EAP' or 'Beta' in their name, rather than working on draft pages which are hidden from public view.

(tick) If you reach a JIRA documentation page for the next major version of JIRA (for example, via a Google search), most headers of these pages have a link that will lead you to the equivalent page for latest official major version of JIRA.

For more information about our reasons for adopting this new process, please refer to our response to JRA-24805.

How to reference JIRA documentation from external sources

If you wish to reference our JIRA documentation from an external source, you may wish to refer to version-specific pages of our documentation, by ensuring that you use the appropriate space key in your URL. For example:

Sometimes, if the functionality of a particular aspect of JIRA has changed, we may need to change the name of a page. For example, due to the significant changes in 'advanced JIRA configuration' in JIRA 4.4, we've had to change the name of:

We almost never change the names of pages in earlier versions of documentation (unless of course they are incorrect).

Last modified on Jul 26, 2012

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.