How do you update a documentation space for a software release?

[Thomas Sherman]

We use Confluence to host our software documentation. This is versioned by space. For example, we have spaces called

• /doc1
• /doc2
• /doc3

We are moving to a system where the current version of our software always has the same spacename, but old ones have a versioned name.

• /doc1
• /doc2
• /doc3
• /current

This has a number of benefits.

• Clients don't use outdated docs by accident
• SEO analytics are not reset every release
• Page history is kept intact
• Don't need to update links in our software product
• We can have our site indexed and clients are taken to the current version

Previously in preparation for a new release I would copy the existing space and give it a spacename for the next version. All my changes would go into this new space. On go live we activate the new space and all our links work.

But now I have space /current that needs a bunch of changes loaded up for our next software release. I need to develop these page updates and release them all at once on /current. How can I do this?

You can't rename spaces, so that is out. I've tried developing the pages in a separate space and copying them in, but I had to copy pages one at a time, including attachments, and it took forever. On top of that, links were always broken because they were developed in the wrong space. There must be a way to do this that isn't awful.

[Matthew J. Horn · Accepted solution]

This is a very relevant question and one that exposes a limitation (or at least a source of frustration with) Confluence: how to hide changes en masse until you're ready to release all of them. Remember, Confluence wasn't originally intended as a documentation platform. The functionality is technically there, but it's wonky.

First thing you do is rename /doc3 to /current, because that's the current version, right? You'll probably have to use the Copy Space plugin to copy /doc3 to /current to achieve the "rename" since you can't change a space's key after it's created (the key being the portion that appears in the URL, not the space's name).

At this point you can go ahead and delete /doc3.

The next step is to copy /current to a working space (a space that will not be visible until you go live). Call this "/doc4working". Hide /doc4working from outside view. Work in /doc4working.

When it's time to go live, copy/rename /current to /doc3 (I know, it used to be called that, but now you're essentially archiving it.

Finally, copy/rename /doc4working to /current and then delete /doc4working.

Some notes:

• Copying spaces maintains the links so you don't have to worry about links pointing back to the copied from space.
• Folks will NOT always know which version of the docs they're in unless you put a big bold note at the top of the page. Don't expect them to look at the URL. In addition to a "NOTE" at the top of the page, I use a totally different color scheme for the "working" space.
• There's a plugin that seems to smoothly handle versioning. I think it's called Scroll Versions or something like that.
• If you make changes to /current, you'll also have to make the changes in /doc4working. It's best to try and minimize the number of changes you make because of this.

Hope this helps,

matt