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

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.

1 answer

1 accepted

This widget could not be displayed.

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

Suggest an answer

Log in or Sign up to answer
Community showcase
Posted Sep 17, 2018 in Confluence

Why start from scratch? Introducing four new templates for Confluence Cloud

Hi my Community friends!  For those who don't know me, I'm a product marketer on the Confluence Cloud team - nice to meet you! For those of you who do, you know that I've been all up in your Co...

595 views 7 6
Join discussion

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you