Back
Use CasesRedirect for ConfluenceViewtracker - Analytics for Confluence

How migrating our app documentation to Cloud made us struggle, then celebrate

bitvoodoo apps documentation

Partial Cloud migration of our documentation in Confluence

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.
We heavily relied on our apps Viewtracker – Analytics for Confluence and Redirect for Confluence for a swift migration. Truth be told: 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’s announcement that they would get abolish their server products, I’ve had this nagging voice inside my head: “Your 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 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 like a good starting point. If we could migrate the documentation without major hiccups, we would tackle the elephant in the room: Migrating our entire bitvoodoo intranet to the Cloud.

Performing a Cloud migration during lockdown: the struggle is real

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:

  1. Deciding which pages to migrate at all.
  2. Performing the actual migration.
  3. Archiving server/DC spaces.
  4. Rewriting existing Confluence links.
  5. Getting rid of our custom-made Enterprise Theme and other handy macros.
  6. Familiarizing ourselves with the Cloud editor.
  7. Converting migrated content from the legacy editor into the new Cloud editor.

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 go into 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. However, I will gladly go into the other topics in a future article if you are interested.

Deciding which pages to migrate to Cloud

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 at all. Keep in mind that each page with a custom-made user macro or a specific app’s macro will be a hassle to migrate.

Data-driven Content Audit

It is also 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:

  • Which content attracts many views? In our case, since the app documentation is public-facing, we were especially interested in page views by external users.
  • Which content has received likes, comments or is being watched? Truth be told, the app documentation usually isn’t where content goes viral 🙂 Still, we have seen comments and likes before (depending on the permission scheme of Confluence).

What better tool to use for this task than our Viewtracker – Analytics for Confluence. For each documentation space, we wanted to see the most popular pages of the last months. Here’s what we did:

  1. Using the CQL filter in the global VT report, we filtered for spaces carrying the space label “docu” (see GIF).
  2. We set the date range to “This year” to accumulate data from various months.
  3. We exported the filtered report as a CSV file.
  4. Organising the data in a spreadsheet (a Google Doc in our case), we could quickly see which content was popular and which wasn’t.
  5. We set a minimum of 20 views for pages to be considered relevant. This is an arbitrary number and might be very different in your case.
  6. We had a closer look at the pages below the minimum count and eliminated quite a few of these.

Unfortunately, we forgot to take screenshots of the process. But here’s a GIF showing how to use the CQL filter in the Viewtracker Global Report:

And here’s how to export the filtered views into a CSV file:

Export Views as a CSV file

Full disclosure: Of course, it is also possible to use SEO tools like Google Search Console to uncover which content is worth migrating. However, this would only work for public-facing Confluence content that is indexed.

Side effects of the content audit

The content audit had quite a few welcome side effects.

  • We found contents that were still relevant but that needed to be linked to more prominently.
  • Some pages’ content could (and should) have been inserted into other pages. Now was a good opportunity.
  • We stumbled across pages that had been outdated for years. Time to get rid of them once and for all.
  • We even found pages with restrictions that should have been removed months ago.

While the audit was time-consuming, we think it was worth taking the time for this late spring cleaning.

Migrating to Cloud

Performing the actual migration

Now that we had established 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.

Archiving server/DC spaces

We then archived the documentation spaces on Server/DC. Since there is no built-in workflow to archive spaces on Server/DC, 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 DC or Cloud?) and drive documentation viewers to the new Cloud instance.

Restricting access to group “confluence-administrators.”

Redirecting existing Confluence links

Once the migration was complete, we could address the following task: How to redirect page viewers to the new documentation pages on Cloud?

As you may recall, we only performed a partial migration (only the app documentation), with most pages remaining on DC. We needed to make sure that existing links would not be broken after the migration, both for user experience and SEO purposes. Here’s an incomplete list of links that needed to remain valid:

  • links from bitvoodoo macros to the documentation
  • bookmarks in browsers
  • backlinks of all kind (blog posts, social media, Marketplace Listing, etc.)

Working with “Redirect to URL” Macros

“Redirect to URL” Macro with an example

To create a page-by-page redirect, we used our app Redirect for Confluence. It contains the macro “Redirect to URL” that lets you redirect a Confluence page to any other URL. Here’s how we proceeded:

  1. For every page considered relevant (see above) on Server/DC, we edited the page and inserted the “Redirect to URL” macro.
  2. We set the new Cloud page’s URL as “Destination URL”.
    Note: We used the complete URL, not the Tiny Link created when sharing a page. Our reasoning behind this: the URLs should contain relevant keywords instead of a jumble of characters and numbers to benefit SEO. The app gave us a pleasant surprise: The redirects still work if pages are moved or renamed on Cloud.
  3. We created a spreadsheet of the redirections in place to keep track of the process.

Measuring impact: Checking the indexing status of the new Cloud domain

No online project is complete without measuring user signals. So we set up a new Google Analytics property for our Cloud documentation bitvoodoo-apps.atlassian.net. It allows us to monitor user behaviour 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 Server/DC 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 behaviour but happy to see that the redirections work swiftly.

Conclusion

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 smooth the migration process itself worked. Still, there were many steps to take before and afterwards that kept us occupied for various weeks.

Pros & Cons of partial migration

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. Possibly, indexing the migrated content on Google would have been more straightforward with a complete migration too. Still, using the app Redirect for Confluence was an excellent alternative to manually rewriting links.

Pros:

  • We used the documentation as a trial balloon, so that the product team could familiarize themselves with Confluence Cloud and all its quirks before the entire company would take the leap.
  • We found an additional use case for our app Viewtracker: Assessing which content was worth migrating in the first place based on concrete numbers was very helpful.

Wait – what about the celebration?

Yes, I skipped the celebration part 🙂 Since the Cloud migration was and is a continuous effort, there never seemed to be the right moment for an official celebration. We did, of course, spread the word 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, there are many spaces that need to complete the content assessment described above before a Cloud migration makes sense.

There is more …

As stated in the beginning, there were (and are) more learnings steps involved in our migration process:

  • Getting rid of our custom-made Enterprise Theme and other macros.
  • Familiarizing ourselves with the Cloud editor.
  • Converting migrated content from the legacy editor into the new Cloud editor.

These kept us from

If you are interested in the details, I will gladly write another blog post or discuss the process with you directly. So don’t hesitate to reach out to me.

Technical Writer Cora Egli
Cora, technical writer at bitvoodoo