🌰 In a nutshell: We at bitvoodoo migrated our app documentation from Confluence Data Center to Cloud. You can now access it via bitvoodoo-apps.atlassian.net. While migrating to Cloud, we heavily relied on our Confluence apps/plugins Viewtracker – Analytics for Confluence and Redirect for Confluence. Truthfully, It did require a lot of work, but it was worth it. Read on for all the details.
Hi, I am Cora, the technical writer at bitvoodoo 👋. I’ve been in charge of bitvoodoo’s app documentation since early 2020, juggling roughly 20 app-doc spaces in close collaboration with our developer team. As bitvoodoo has been using Atlassian tools since 2008, we have built our documentation – and our entire intranet, on that matter – on Confluence Server & Data Center.
Ever since Atlassian announced that they would abolish their server products, I’ve had this nagging voice inside my head: “Your Confluence documentation should be done on Cloud, too”. The voice refused to be ignored in spring 2021, by which time we had four cloud-ready Confluence apps/plugins on the market.
If we wanted to act credibly and keep up with the latest development, we would have to use Confluence Cloud daily. The app documentation as a subset of our intranet seemed a good starting point. If we could migrate the Confluence documentation without major hiccups, we would tackle the elephant in the room: Migrating our entire bitvoodoo intranet to Confluence Cloud.
But it seemed like a Herculean task in the spring of 2021 when everybody was working remotely and hesitant to take on more assignments. Some of the tasks, truth be told, looked incredibly tedious:
In its entirety, the task looked overwhelming. So we decided to be agile about it and split the main task into clearly laid out sub-tasks. It probably won’t surprise you that we used Jira for this part of the project. But this article is about Confluence, and I won’t explore any project management details here. I will focus on the tasks necessary to migrate Confluence content to Cloud instead.
To make the process more easily digestible, I will focus on the first four items on the list in this article along with some Cloud migration best practices. However, if you are interested, I will gladly go into the other topics in a future article.
Atlassian states it clearly in its guide to Cloud Migration: It is essential to assess the content on your existing system and decide which content is worth migrating to Cloud at all. Remember that each page containing a custom-made user macro or a specific app’s macro will be a hassle to migrate.
It is essential to ask yourself: Does this page still spark joy? Is it still relevant? This assessment can be a painful task for content managers and technical writers who deeply care about their content. Instead of going into emotional debates about which content may stay and which should go, it is better to focus on hard facts:
What better tool for this task than our own Confluence app, Viewtracker – Analytics for Confluence? Here’s how we proceeded to find content with very few views (the respective documentation pages are linked below):
These settings resulted in a table listing all content with fewer than 20 views this year:
Full disclosure: Of course, it is also possible to use Search Engine Optimization (SEO) tools like Google Search Console to uncover which content is worth migrating to Cloud. However, this would only work for public-facing Confluence content that is indexed.
The content audit had quite a few welcome side effects.
While the audit was time-consuming, we think it was worth taking the time for this late spring cleaning.
After establishing the relevant content, we could migrate it to our new Cloud instance in a matter of hours. We used the Atlassian Migration Assistant and didn’t encounter any significant problems. There is a mass of material on the actual migration process provided by Atlassian, so I will not go into any details here.
Viewtracker – Analytics for Confluence has an automated app data migration. Of course, we also migrated our loyal Viewtracker – Analytics for Confluence app to Cloud. Conveniently, Viewtracker has an automated cloud migration path, as pointed out by Atlassian too.
We then archived the Confluence documentation spaces on Data Center or Server. Since there is no built-in workflow to archive spaces on Data Center or Server, we decided to change the space permissions. They used to be public (i.e., accessible to anonymous users). Now, they are restricted to Confluence administrators. This step was necessary to avoid duplicate content and user confusion (which content is relevant, the one on Data Center or Cloud?) and drive documentation viewers to the new Confluence Cloud instance.
Once the migration to Cloud is complete, we can address the following task: How to redirect page viewers to the new Confluence documentation pages on Cloud?
As you may recall, we only performed a partial migration (only the app documentation) to Cloud, with most pages remaining on the Data Center. We needed to ensure that existing links would not be broken after the migration for user experience and SEO purposes. Here’s an incomplete list of links that needed to remain valid:
To create a page-by-page redirect, we used Redirect for Confluence by bitvoodoo. It contains the macro “Redirect to URL” that lets you redirect a Confluence page to any other URL. Here’s how we proceeded:
No online project is complete without measuring user signals. So we set up a new Google Analytics property for our Confluence Cloud documentation. It allows us to monitor user behavior and identify problems like broken links. So far, we have not noticed any major issues or heard anything negative from customers.
Indexing the Cloud pages in Google seems to take a long time: As of November 21, 155 documentation pages are indexed, and the SERPs are far from ideal. However, this issue existed with Confluence Data Center or Server already.
Google still indexes over 500 documentation pages under the old instance wiki.bitvoodoo.ch, whereas the search results, when clicked, are directly opened in the Cloud instance. We are still puzzled by this behavior but happy to see that the redirections work swiftly.
Performing a Cloud migration is never an easy task. It requires both a clear vision and much attention to detail and should always be a team effort. We were pleasantly surprised at how smoothly the migration process to Confluence Cloud itself worked. Still, there were many steps to take before and afterward that kept us occupied for various weeks in order to keep up with Cloud migration best practices.
In our case, migrating only parts of our knowledge base to Cloud had pros and cons.
➖ Cons
The manual redirection of documentation links caused extra work. This would not have been necessary if we had migrated our entire knowledge base. Also, indexing the migrated content on Google would have been more straightforward with a complete migration. Still, using the Confluence app Redirect for Confluence was an excellent alternative to manually rewriting links.
➕ Pros
We spread the word about migrating to Confluence Cloud at bitvoodoo, which led other space owners to request a Cloud migration of “their” spaces. This was granted for spaces without any app-specific macros. However, many spaces need to complete the content assessment described above before a Cloud migration makes sense.
As stated in the beginning, there were (and are) more learnings steps involved in our migration from Confluence Server to Cloud process:
These kept us from migrating all our content to the Cloud in one go. However, by the end of 2021, all content worth migrating was on the Cloud 🎉.
Are you in the process of migrating Confluence to Cloud? Reach out to bitvoodoo to learn more about migrating Confluence server documentation to Cloud.
