This is the fourth in a series of posts from Atlassian’s Technical Writing Team focusing on using a wiki for technical writing. Last week, Sally Hawse wrote about time-saving ways to re-use content. In this post, I’ll be talking about how to manage the documentation release process using Confluence.
The product launch is drawing close. You’ve carefully crafted your new documentation pages and updates. Now comes the task of releasing them in coordination with the release of the product to which they relate.
But first you will need to take care of the versioning.
How do you version a wiki?
If you’re documenting a software product, you will typically need to maintain different versions of the documentation: one for each version of the product. So how exactly do you use a wiki to publish multiple sets of documentation for the same product? Confluence can do this wonderfully well. On the Atlassian documentation wiki, for example, you will notice that the dashboard lists a space for each major version of every product:
A cut-down list of versions is also shown within each space, in the left-hand navigation – for which we are indebted to the Documentation Theme. The ability to View this page in the current documentation is brought to you by the Space Jump Macro.
Step 1: Copy Existing Documentation
At Atlassian, we create a new space to house the previous version of the documentation. The documentation for the very latest version of every product resides in a master space which uses just the product name as its space-key, e.g. “Jira” (http://confluence.atlassian.com/display/JIRA). This makes life easier for our Support team, among others, as they know that their favourite URLs – e.g. http://confluence.atlassian.com/display/JIRA/Upgrading+Jira – will always refer to the most recent version.
For older versions, we use a combination of the product name plus version number as the space key, e.g. “Jira041” for the Jira 4.1 documentation, “Jira040” for the Jira 4.0 documentation, etc.
When preparing for the Jira 4.2 launch, for instance, we simply created a copy of the “Jira” space, and gave it the key “Jira041”. The easiest way to create a copy of a Confluence space is to use the Copy Space Plugin:
Step 2: Update Master Space
We then added the Jira 4.2 documentation to the master “Jira” space, keeping it hidden from public view, using page restrictions, until the launch date. Note that we also kept the new “Jira041” space hidden (using space permissions) until the launch of Jira 4.2.
Step 3: Remove Restrictions and Re-brand
On the day of launch, we removed any page restrictions and re-branded the master space by changing the space name to “Jira 4.2”, and updating the space’s left-hand navigation (see Configuring the Documentation Theme).
What about the Online Help?
At Atlassian, because our documentation is also the contextual online help for our products, we need to ensure that the online Help links within our applications point to the correct version of the documentation.
As an example, let’s look at the Jira Search screen:
…specifically the “Help” link (ie. the yellow question-mark). If you are using Jira 4.1, clicking the “Help” link will take you to the following page – http://confluence.atlassian.com/display/JIRA041/Performing+Text+Searches
If you are using Jira 4.0, you will be taken here instead – http://confluence.atlassian.com/display/JIRA040/Performing+Text+Searches
But what about the help links for the latest version of the product, which is always documented in the master http://confluence.atlassian.com/display/JIRA space? How do we get the online help for Jira 4.2 to point to the Jira space while 4.2 is the latest version, then to the Jira042 space in the future, when Jira 4.3 is launched?
We achieve this by coding the following into the product when referencing the online help, as the first part of each URL – http://docs.atlassian.com/jira/docs-042/. We then configure our web server to redirect http://docs.atlassian.com/jira/docs-042 to http://confluence.atlassian.com/display/JIRA
When Jira 4.3 launches, we will simply redirect http://docs.atlassian.com/jira/docs-042 to http://confluence.atlassian.com/display/JIRA042. The advantage of using a redirection is that it can be changed at any time – unlike the URLs within the product, which of course cannot be changed once the product has shipped.
So what exactly do you publish, and when?
If your product is releasing a public Beta before launch, then you may want to publish your technical documentation to coincide with the Beta so as to help your existing customers quickly find their way to the new product features. Or in other cases, you may be mandated to keep the documentation hidden until launch day, so as to generate maximum marketing impact from the new features.
Either way, here is a high-level overview of the steps we follow at Atlassian when releasing documentation:
Prior to launch
- Create a copy of the latest space (using the Copy Space plugin as described above). Name it after the previous version, and hide it.
- Add your new documentation to the master space, keeping it hidden (see previous blog).
- Check that the online links inside the product point to the appropriate documentation.
On day of launch (or the evening prior)
- Unhide (remove viewing restrictions) the new space (i.e. the space containing the previous version’s documentation).
- Unhide (remove viewing restrictions) your new documentation in the master space.
- Re-brand the master space to the latest version.
- Update the redirections on the web server.
The long-awaited day dawns. The product managers are tweeting excitedly. The support team are looking tense, awaiting the avalanche of upgrade-related queries (which of course won’t eventuate, because you’ve done such a superb job of the upgrade guide).
And your brand new documentation awaits its readers.
Start using a wiki for technical writing for $10
With perpetual, full-featured licenses starting at $10 for 10 users, Confluence is an ideal solution for your technical documentation needs.
All Confluence licenses allow for unlimited anonymous users.
