Child pages
  • Managing the Life Cycle of your Technical Documentation
Skip to end of metadata
Go to start of metadata

This page is part of the guide to developing technical documentation on Confluence Wiki. We have already shown you how to create your technical documentation space, including how to set permissions for your space. Now we offer a quick-start guide to managing the life cycle of your technical documentation in Confluence. The life cycle includes drafting, reviewing and publishing a document, as well as managing documentation that is release-specific.

Quick guide to managing the technical documentation life cycle

  • Create draft pages with restricted permissions, to hide them until they are ready for publication.
  • Set the permissions to allow reviewers to comment on and/or update the pages.
  • When ready, publish the page by removing the permission restrictions.
  • Monitor updates to your draft and published pages by watching your space and/or subscribing to RSS feeds.
  • Use spaces as a mechanism for matching your documentation version to product releases: one space per major release number.
  • Consider installing plugins for extended workflow and publication management.

The rest of this page gives more details of the above procedures.

Using the Built-In Confluence Functionality to Manage Workflow and Release Cycle

This section describes how to use the built-in Confluence functionality to manage your workflow (draft, review, publish) and to align your documentation version control to the product release cycle.

In this scenario we also assume that you want a live space that always has the same space key and always contains the latest version of your documentation. This scenario suits the requirements of an organisation that wants their technical documentation to be 'live'. Various groups of people can refine the content as and when required. People can also subscribe to the space, knowing that they will always get the latest version of the documentation and comments.

This is the way we manage our documentation at Atlassian. The content of the wiki is dynamic, continuously updated, commented on, subscribed to and watched by thousands of people all over the world.

Drafting, Reviewing and Publishing a Page

The workflow is simple.

  1. Create a page with restricted permissions. For example, you might restrict viewing to a group of people such as your team. On a public wiki, you might restrict viewing to staff members, so that the general public cannot see the page.
  2. Write the page content.
  3. Ask other people to review the page. They can add comments to the page or simply edit the page content directly.
  4. Publish the page when ready, by doing the following:
    • Delete the comments on the page.
    • Remove the permission restrictions on the page. The page has now been published. The space permissions and site permissions now determine who can see and/or update the page.

The screenshot below shows a page under review. Notice the lock icon at top left, indicating that restricted permissions apply to this page.

Keeping Track of Documentation Updates

On a wiki, it is quite usual for a number of different people to update a single page. Technical writers need to know what happens to our documents, both during review and after publication.

Viewing the History of a Page

Confluence creates a new version of the page every time someone edits the page. The page history shows all the versions, with date, author, and any comments made on the update.

Go to the page, open the 'Tools' menu and select 'Page History'. The 'Page History' view will open, showing a list of all versions of the page, ordered from newest at the top to oldest at the bottom.

On the page history view, you can:

  • View the content of a specific version of the page.
  • Revert to (restore) a specific version.
  • Select any two versions and ask for a comparison, to see what has changed between those two versions.

See Page History and Page Comparison Views for detailed information.

It is all very well to go to a specific page and see what has happened to it, but how do you know when to go and look at the page? You need a notification of any changes made to your documentation space.

In Confluence, you can monitor updates to your documentation via email notifications and via RSS feeds.

Receiving Email Notification of Updates

You can 'watch' a page or an entire space. Whenever anyone updates the page or space, you will receive an email notification.

To watch a page:

Open the 'Tools' menu and select 'Watch'.

To watch a space:

  1. Go to a page in the space, open the 'Browse' menu and select 'Advanced'.

  2. In the left-hand panel, click 'Start watching this space'.

See Subscribing to Email Notifications of Updates to Confluence Content for details of the various notifications Confluence will send, and how to configure your notification settings.

Monitoring Updates via RSS Feeds

RSS feeds provide another way to keep track of updates. The simplest way to build an RSS feed is to use Confluence's feed builder, accessible from the dashboard. This will give you a URL that you can ping to get the latest updates.

Below we describe how to set up a useful feed for your technical documentation space. Remember that you can adjust the settings to suit your own needs.

  1. Go to the dashboard and click the 'Feed Builder' link located above the list of spaces. The RSS feed builder form appears.
  2. Check the boxes to select all the content types. (Even if you are not expecting comments, blog posts or mail in your documentation space, it does no harm to receive notifications if they do arrive.):
    • Pages and the comments and attachments on pages.
    • Blog posts and their comments and attachments.
    • Mail.
  3. Select your documentation space from the list. Press Ctrl and click to select multiple spaces.
  4. Click the 'Create RSS Feed' button to create your feed.
  5. This will take you to a new screen. Drag or copy the link into your RSS reader. The feed URL is linked to the words 'Drag or copy this link to your RSS reader'.

Now that you have set up your RSS feed, you need to decide how to read it. There are various options to choose from. For example:

See Subscribing to RSS Feeds within Confluence for details.

Release Management

Let's assume that your product goes through a regular release cycle, and that you need to retain separate documentation for each major version of the product.

At Atlassian, we use spaces as our version-control mechanism.

  • Archive spaces. At each release, we create a new archive space to house the previous version of the documentation.
  • The live space. The documentation for the latest version of the product resides in the live space. The live space always retains the same space key and is always available for viewing and updating.

Space Keys

The live space has just the product name as its space key. For example, for the Crowd product the space key is 'CROWD'. (See the Crowd documentation space.)

For the archived versions, we use a combination of the product name plus version number as the space key. For example, we use 'CROWD020' for the Crowd 2.0 documentation, 'CROWD016' for the Crowd 1.6 documentation, and so on.

The Release Management Process

Here is an overview of the process we follow at Atlassian.

  1. Leading up to release date. Work with hidden draft pages in the live space. A 'hidden draft' is simply a page that has restricted permissions applied:
    • For each new feature, create a new page with restricted permissions.
    • If you need to update existing pages, create a hidden copy of the existing page and apply the updates to the copy.
    • Follow the usual draft and review procedure for each page.
  2. A few days before release date. Use the Copy Space plugin to copy the live space to a new space. This creates a snapshot of the current documentation, and will act as an archive for the current release which is soon to become the previous release. (We described the use of the Copy Space plugin in the earlier section of this guide: Creating your Technical Documentation Space.)
  3. On release date. Publish the updated documentation for the new version of the product:
    • Rebrand the live documentation space to reflect the new release number. In other words, change the space name and any other descriptions that include the product release number.
    • Unhide all the new pages, by removing the permission restrictions on each hidden page.
    • Copy the content of the updated pages to the proper pages, then delete the copies.
    • Export the newly updated space to PDF, HTML and XML, for those customers who prefer offline versions of the documentation.

Note that the above process is applicable to major releases of the product. For minor bug-fix releases, we simply update the documentation in the live space. We do not create archive spaces for every minor release.

The example below shows an extract from the dashboard of our documentation wiki, listing the spaces for different versions of the Crowd documentation. (Crowd is one of our products.) Each space holds the documentation for a specific major release of Crowd.

Other Scenarios using the Built-In Confluence Functionality

It is easy to design other ways of managing your documentation spaces using the built-in Confluence functionality. For example, the simplest scenario is to publish a new space for every new release of your product, using the same Copy Space plugin as described above.

Using Plugins for Extended Workflow and Publication Management

For advanced workflow features, consider installing the Ad Hoc Workflows plugin onto your Confluence site.

Similarly, consider using the Content Publishing plugin to publish content from a master space to a published space. In this scenario, you will create a master space that contains your drafts in progress and new releases. The master space is visible only to the authors and reviewers. You will periodically publish the master space to a published space. This suits the requirements of an organisation that needs a 'published' or 'official' set of documentation, published only when a new version of the product is released. There is no requirement for continual updating of the documentation.

  1. Install the Content Publishing plugin.
  2. Create a space for your master content.
  3. Create a space for your published content.
  4. When the content in the master space is ready to publish, go to the 'Advanced' tab in the 'Space Admin' section of the master space.
  5. Click 'Publish Space' to configure the settings and then publish your space. See the plugin documentation to choose the options best for your needs.
  6. Click "Publish'.

(info) Automatic publishing. The Content Publishing plugin can work together with the Ad Hoc Workflows plugin to publish pages automatically when the page reaches a specified state in the workflow.


  • Installing plugins. If you decide to use additional plugins, your site administrator will need to install the plugins into your Confluence site. Refer to the documentation on installing plugins.
  • Plugin support.
    Before installing a plugin into your Confluence site, please check the plugin's information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines on plugin support.
Next Steps

Now you know about managing your workflow and documentation release process on Confluence. What next? Take a look at Providing PDF Versions of your Technical Documentation.