Wiki docs – release management
A wiki is a living organism. Its content is dynamic, continuously updated, commented on, subscribed to and watched by thousands of people all over the world. How does this work with technical documentation that is release-specific? Can you baseline your documentation? What if you are documenting a piece of software or some other product that goes through a regular release cycle, and your customers need to access the documentation which corresponds to their specific version of your product? This is elementary release management, bread and butter to technical writers. But can a wiki do it?
This week I created an archive space on our Confluence documentation wiki, in preparation for an upcoming major release of Atlassian Crowd. So now’s a good time to talk about the way we manage the technical documentation in correlation with our software releases. And to find out how other people are doing it.
Let’s say your wiki pages tell people how to use a toaster. And let’s say the very latest toaster in the product line, due out before Christmas, has a bright new quick-toast button. But there are thousands of customers out there who already have the original product and rely on it heavily – even without the shiny new button. What should your documents say about the button? Even more complicated: What if the toast-insertion mechanism is about to change from the old shove-it-in-by-hand method to a fancy new sliding widget?
There are a few strategies:
- Have separate documents for each version of the toaster.
- Have only one document, describe all features including the newest, and add a note that the quick-toast button is available only on the latest toasters. Also explain how the toast-insertion functionality has been enhanced. You could even hint that your customers should consider upgrading their toaster.
- Ignore older versions of the product, and only give instructions on using the very latest version.
- Any more? Let me know how you’ve done it.
We’ve chosen the first option. The second might result in a long list of notes, tracking a feature’s changes through the various releases of the product. This might become confusing in the long run. (But the second option does have its attractions – it’s a lot simpler, from the point of view of document management.)
We make use of ‘spaces’. A space is a sort of wiki-within-a-wiki, and is part of a Confluence wiki. If your wiki doesn’t allow spaces, then you might consider having separate wiki instances for each software release.
Here’s how we do it:
- The ‘main’ documentation space always contains the documentation for the latest release of the software – such as Crowd.
- ‘Archive’ spaces contain the documentation for each previous major release of the software – such as Crowd 1.0.
- We also provide PDF, HTML and XML versions of the documentation – here they are for all the Crowd releases.
Update November 2009:
- We use the Copy Space plugin to make the archive copies of the space. Note that the Copy Space plugin isn’t supported by Atlassian. But we use it. 🙂
- If you like, you can vote for or comment on our JIRA request to have the plugin shipped with Confluence, or at least supported.
The fly in the ointment.
That sounds quite simple, huh. But as usual, there are some idiosyncrasies which need a bit of working around. The tricky bit is in the first bullet point above – the ‘main’ space always contains the documentation for the latest software release.
So we can’t start adding information about the new release until release date. And we can’t archive off the current space or create a new ‘draft’ space which will take its place at release date.
Why not? Two very important reasons:
- Lots of people all over the world have hyperlinks into the documentation space, and subscribe to RSS feeds from it, and add ‘watches’ to pages on it, and comment on it. So we can’t archive the existing main space – that would break all their links and stuff.
- The wiki is alive. As well as the technical writers, we have support staff and developers continuously updating the content. If we created a draft space and then later used it to replace the current space, we’d lose all updates made since the draft was created. And if we ‘froze’ the current space, the wiki wouldn’t be alive.
The fly catchers.
How do we solve the problem? Well, it takes a fair bit of organisation, and the help of a couple of tools.
When documenting new features for the upcoming release, we create pages in the wiki and ‘hide’ them from public view using Confluence’s page restriction functionality. And we make a note to ‘unhide’ the page on release date.
When we need to add or change existing pages due to changes in the upcoming release, we can’t make the change until release date. So we make detailed notes about the changes that need to be made.
Some time before release day, we make an archive copy which will become the documentation for the previous release (now still the current release).
On release day, we first update the space description so that it refers to the latest software release. Then we go through our ‘unhide’ and ‘update’ notes, applying the changes to the main space.
Where do we make the notes, you may ask? In a JIRA task, of course.
Summing it up:
Yes, a wiki can handle release-dependent documentation reliably and usefully. It’s pretty similar to using any other documentation system – find the tools that will help, and then make a plan to make them work to your requirements.
Wikis save trees.
Completely off topic 🙂 but I wanted to add a pretty picture because release-management is a bit of a dry subject. Here’s a gum tree we came across this week, while walking through the Manly Dam parklands. The multi-coloured bark is a lovely sight, and quite common too. Does anyone know the name of this tree?
Posted on 17 November 2007, in atlassian, Confluence, Crowd, environment, technical writing, trees, wiki and tagged atlassian, Confluence, documentation, Ozzie trees, release management, technical documentation, technical writing, trees, version control, wiki, wikis. Bookmark the permalink. 21 Comments.