How did Atlassian get its previous Confluence doc versions into Scroll Versions?

[Jackie Wheeler]

Currently, we have a separate space for each version of our product documentation (e.g., <productname>100, <productname>200, etc.). In this approach, each space has a different URL, which creates SEO problems, because users searching via Google always find older versions of the docs first.

We are interested in doing what Atlassian did for the Confluence docs: using Scroll Versions to create a single URL for a product's documentation and a Version drop-down that lets users select the version they want to see. However, after talking to the Scroll folks, we learned that you can't import your existing spaces into a single space and assign them versions. Here's what they said:

"I have tested the steps described in the article on importing the content into a specific version, and unfortunately, it won't be possible to import pages from multiple spaces under one space. Page trees would be separate in the versioned space if you use the URL to import pages in one versioned space.

This is related to the fact that upon importing, Scroll Page Ids are different as Scroll Versions doesn't know, to which already versioned page the imported page is referring to. Scroll Page Ids are used to determine different versions of a single page.
You would have to version pages after initial import manually unfortunately."

How did Atlassian do this for the Confluence docs when they switched to Scroll Versions? Did they manually tag the version in every page in all their existing docs after importing? Has anyone else successfully imported previous versions of their docs into a single space for use with Scroll Versions without manually versioning every page?

[Rachel Robins]

Hi Jackie, 

I'm the tech writer for Confluence here at Atlassian, and worked on the original rollout of Scroll Versions for Atlassian's documentation. I'm happy to share the way we did it.  This was quite a few years ago now, so there may be easier or better ways to achieve some of these steps now. 

Our pre-scroll versions workflow relied on making changes to a 'latest' space, and then copying that space to create an 'archive' space for a particular version, just before we started making changes for the next version (for example, the content of the 'latest' space would be 5.1, and we'd copy that space to create the 5.1 archive space, and then start making changes to the latest space for 5.2). So like you, we ended up with a seperate space for the docs for each product version.  One thing we were very keen to maintain, when starting to use Scroll Versions, was our 'latest' spaces, as they performed well in search, and often had a lot of incoming links. 

Our rollout approach was:

1. Copy the 'latest' space (we used the Copy Space plugin at the time. A more reliable method now would probably be to create a new blank space, and then copy the homepage and all its child pages to that new space). 

2. Clean up the copy - we removed any restricted pages, or pages we didn't want to use scroll versions to manage. 

3. Enable Scroll Versions, but don't create any versions or make changes yet. 

4. Use the Scroll Versions REST API to copy scroll page IDs from our new master space to our existing 'latest' space.   (/rest/scroll-versions/1.0/support/copyIds/MASTERSPACEKEY/LATESTSPACEKEY)  this meant that when we attempt to publish from the master space into the latest space for the first time, it recognises the pages correctly.  This is an important step if you want to be able to publish to your existing spaces.  You can tell when it has worked, because the publish preview stops trying to add the pages as new pages. 

At this point, the master space was ready for us to start creating versions and making changes etc. We would publish a version into the latest space, and then publish to a new space, to create the versioned archive space (this replaced our old process of copying the space). 

It's worth pointing out that there are a few different approaches to versioning your docs. We chose to keep our master space private, and always publish major versions out to seperate, public spaces.  I believe now it is very common to make your master space public, and use the Scroll Versions version picker to allow end-users to navigate between published doc versions. It certainly cuts down a lot of unnecessary duplication. 

Because we weren't diverging from our existing approach of a seperate space for each product version, we took a 'Scroll Versions from now on' approach for every rollout. So the first docs to be managed in Scroll Versions were Confluence 5.2, I didn't try to import changes from earlier versions into the master space at all. Several years on my master still has the 5.2 changes, and about 100 other versions. 

In terms of version navigation for users, we now use Scroll Viewport on confluence.atlassian.com. In the theme, we built a version picker that we can configure to point to particular archive spaces for each version of the docs.  A better approach these days might be to expose the actual Scroll Versions version picker, so that you have less duplication of content, and don't need to manually configure a version picker like we currently do. 

I'd recommend talking to K15t directly to see what your options are. I certainly wouldn't recommend continuing to have a seperate space per product version, unless it really is the best option for you.  The Scroll Versions REST API has grown quite a bit since I was first working on our rollouts, and there may be ways you can achieve a good result, with less duplication than we currently have. 

Good luck with it!  I really enjoy using Scroll Versions, and have found, through numerous rollouts for other product's docs, that you really benefit from carefully thinking through your rollout strategy and making a plan first. 

[Christian Reichert (resolution)]

Thanks for sharing this. An interesting insight.

[Jackie Wheeler]

Thank you so much, Rachel! That's a huge help. I really appreciate your taking the time to share all the steps with us.