Managing the Life Cycle of your Technical Documentation
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 add-ons for extended workflow and publication management.
The rest of this page gives more details of the above procedures.
On this page:
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 as follows.
- 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.
- Write the page content.
- Ask other people to review the page. They can add comments to the page or simply edit the page content directly.
- 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 and choose Tools > Page History.
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.
- Log in to Confluence, if you have not already done so.
- Go to the page or blog post.
- Choose Watch and select the relevant check box.
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. 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.
- Choose Help ? > Feed Builder. The RSS feed builder form appears.
- 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.
- Select your documentation space from the list. Press Ctrl and click to select multiple spaces.
- Choose Create RSS Feed.
- 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.
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 Bamboo product the space key is 'BAMBOO'. (See the Bamboo 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 'BAMBOO040' for the Bamboo 4.0 documentation, 'BAMBOO041' for the Bamboo 4.1 documentation, and so on.
The release management process
Here is an overview of the process we follow at Atlassian.
- 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.
- A few days before release date. Use the Copy Space add-on 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 add-on in the earlier section of this guide: Creating your Technical Documentation Space.)
- 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 Bamboo documentation. (Bamboo is one of our products.) Each space holds the documentation for a specific major release of Bamboo.
Screenshot: Archive Bamboo spaces and Bamboo Latest for the current version of the documentation.
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 add-on as described above.
Using add-ons for extended workflow, publication and version management
For advanced workflow features, consider installing the Ad Hoc Workflows add-on onto your Confluence site.
For advanced publication and concurrent version management consider using the Scroll Versions add-on. With Scroll Versions, you can set up and manage concurrent versions of your documentation in a single space. You can manage multiple versions of software, different product variants, and even multiple languages of documentation. Plan your page updates for a specified version and then publish them all at once.
See the documentation of Scroll Versions for more information.
Similarly, consider using the Content Publishing add-on 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 add-on can work together with the Ad Hoc Workflows add-on to publish pages automatically when the page reaches a specified state in the workflow.
- Installing add-ons. If you decide to use additional add-ons, your system administrator will need to install them into your Confluence site. Refer to the documentation on Installing add-ons.
- Add-on support. Before installing an add-on (also called a plugin) into your Confluence site, please check the add-on's information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines on add-on 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.
Was this helpful?
Thanks for your feedback!