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.
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.
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:
To watch a 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.
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.
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.
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.
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.
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.
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.