Confluence 3.5 : Managing the Life Cycle of your Technical Documentation
This page last changed on Jan 11, 2011 by smaddox.
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.
The rest of this page gives more details of the above procedures. Using the Built-In Confluence Functionality to Manage Workflow and Release CycleThis 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 PageThe 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 UpdatesOn 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 PageConfluence 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:
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 UpdatesYou 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:
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 FeedsRSS 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. Release ManagementLet’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.
Space KeysThe 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 ProcessHere 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 FunctionalityIt 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 ManagementFor 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.
Notes
Next StepsNow 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. |
![]() |
Document generated by Confluence on Mar 16, 2011 18:25 |