Knowledge base migration from a Technical Writer’s perspective
This is the story of a knowledge base that migrated from Atlassian Confluence to Microsoft SharePoint. It was a six-month saga, which is almost over. So, let me share how it went and what we learned in the process.
I was one of the first Tech Writers who contributed to that knowledge base. I was the one who saw it raw and plain (basic Confluence version) with just the first few sections and then watched it follow the latest trends in technical writing and grow and flourish (with add-ons, macros, plugins, and customizations). The knowledge base evolved from a few hands to a bustling hub with dozens of contributors. As the Technical Communicators’ team expanded, they introduced an internal writing style guide, a rigorous review process, and specific roles like an information architect to ensure the knowledge base remained current, consistent, and clear. However, years of operation couldn’t but affect that intended ideal state.
1-to-1 content migration vs. complete makeover
To me, a knowledge base sometimes resembles a wardrobe. You start with empty shelves, gradually buy new clothes, and create a matching outfit. To stay up to date with fashion trends, you add new elements, keeping a balance between old and new. When you no longer need some clothes, but it’s too early to bid them farewell, you tuck them on the farthest shelf, only to forget about them for years.
Isn’t it a story of the content? You create a structure for a knowledge base and develop topics, making them look and sound consistent. You try new technical writing techniques and use add-ons to better represent certain information. You don’t delete but keep outdated information for reference, place it in a folder with limited access, move it somewhere, and then forget it exists.
With years and without proper maintenance, even a well-structured knowledge base may become like an old wardrobe—cluttered, untrendy, too heavy, and not functional at all.
So, when the question about the migration of a knowledge base arises, it’s always an excellent opportunity to avoid doing a one-to-one migration and make a complete makeover.
SharePoint as a new bright future
To prepare for the migration, it’s critical to investigate the to-be state: compare the tools, check benefits, analyze risks, and work on possible limitations. For us, a to-be knowledge base platform was Microsoft 365 SharePoint: we use other Microsoft tools a lot, and it’s reasonable to keep everything within one ecosystem. What did we know about SharePoint? We used to store files on SharePoint to make them accessible within teams, but we never considered it as a place for a knowledge base, an intranet, or anything more than file storage.
As it usually comes with a new tool, we were rather skeptical. We compared a lot, we noticed a lot of limitations, and we were pushing away the very idea of migration. Typical stages of acceptance: denial, anger, depression, bargaining, and, finally, acceptance.
Let me list a few recommendations on how to minimize stress and decrease the time needed to move to a new technical writing environment. Do everything possible to build a new muscle.
- Learn about the new tool: check the official website (it was SharePoint Help & learning for us) and other resources too — YouTube videos, learning materials on Udemy or other platforms, blogs, etc.
- Google for use cases of similar migrations. Learning from the other’s experiences can provide valuable insights.
- Talk to your IT team about the required vs. nice-to-have features to select the most suitable option. Check what comes with a standard package and what the possible extensions are.
- Ask product reps to help you set up the new component in your existing technical writing environment, especially when it comes to a new complex component.
- Request a demo environment for testing purposes. It’s always a great idea to thoroughly test before moving to the production environment.
- Check what the to-be state may look like. For example, the SharePoint look book showcases a variety of website/intranet/knowledge base samples designed for different purposes, which is a valuable resource for inspiration.
Believe me — having a solid understanding of a possible to-be state makes the whole transformation much more fun. So, let’s move on with my journey!
Preparing content for a smooth migration
Great results don’t happen by chance. Proper preparation is a key. Here are some essential areas to focus on if you’re planning a similar content migration.
Thorough content audit
To avoid unnecessary “burden”, revise all outdated, deleted, and internal-use content, so that only the necessary information migrates to SharePoint. Conducting an audit in a familiar environment makes this task easier. So, make sure to check:
- Hidden pages. Detect any pages or sections that are called “archive”, “outdated”, or similar. Undeleted content may reside there, hidden from users but still accessible within the system.
Also, go to Space tools > Permissions > Restricted Pages. This is where the admin of a Confluence space may detect pages restricted for access. - Deleted (yet still restorable) pages. Revise all deleted pages: go to Trash and click Purge all to permanently delete all the unnecessary pages.
- Empty pages. Are there any placeholder pages that you’ve created but never filled in? Do you really want them to move to a new environment?
Additionally, check Space tools > Content Tools > Undefined Pages. This is where an admin of a Confluence space may detect non-existing pages that are linked from within Confluence. - Non-standard macros. It is important to note that certain Confluence macros, such as children display, table of contents, excerpt include, aui-icon, and others, may not migrate seamlessly to SharePoint. Additionally, any styling and customizations done using HTML and CSS may not be replicated on SharePoint. In the context of migration, it is better to follow the “the simpler, the better” rule. Simple content and formatting tend to migrate more smoothly between platforms.
In-depth permissions and restrictions audit
Document space permissions and page restrictions in a stakeholder matrix to facilitate their recreation in your new technical writing environment. This matrix will help you review which users or user groups should have access to specific information and determine the level of access—whether it is view-only, edit, or admin rights.
- Space permissions. Permissions are used to allow access across the whole space, so there you should give your visitors the maximum possibilities. Permissions overlap the restrictions.
On Confluence, go to Space tools > Permissions, make sure permissions are set up according to your needs, and do the necessary cleanup (grant permissions by mail groups rather than individual users one by one, delete inactive users or user groups, etc.).
- Page restrictions. Restrictions restrict actions on the page level and should be used cautiously, considering the influence of space permissions. Create a spreadsheet of the main sections of your Confluence space and fill it in with the global space permissions and page restrictions. Viewing the big picture can help you identify conflicts between your space permissions and page restrictions.
Since SharePoint does not have the concept of pages and subpages, and page restrictions should be set individually for each page, it may be reasonable to split your knowledge base into two or three separate sources. This way, you can manage site permissions more effectively and ensure that access is granted or restricted to the desired level.
Space structure revision
Unlike the Confluence page hierarchy approach, all SharePoint pages are stored in a single “repository”. As a result, the parent-child relationship that exists in Confluence may be lost after migration. Moreover, SharePoint does not have automatic page navigation, requiring manual configuration of a navigation tree. So, revise your existing navigation tree in Confluence. Identify any necessary fixes or adjustments to your current structure to ensure it can be recreated effectively in SharePoint.
Automation in Technical Writing? Yes!
It’s important to consider the available tools that can streamline the content migration task. Such tools can come bundled with migration solutions or be offered as add-ons, helping to simplify the process and save valuable time for more important endeavors.
In our migration journey, we tested several tools and found WikiTraccs the most suitable for our needs. Not only does it speed up a migration from Confluence to SharePoint, WikiTraccs also transforms Confluence macros, links, and images into their SharePoint equivalents.
Executing the migration
After ~ two months of preparation, we were ready to initiate the content migration process. Within just a few hours, WikiTraccs did its magic and migrated all the content to the SharePoint communication site. However, even though the content moved to a new place, it was too early to open it to a broad audience.
After quickly reviewing the migrated knowledge base, we identified the following aspects that required further action:
- There were surprisingly many site assets. Since we didn’t revise all attachments before the migration, it became apparent that additional cleanup was required.
- The temporary Page Tree that WikiTraccs provided was a great helper, considering SharePoint does not automatically generate a navigation tree. Moreover, it also revealed previously inaccessible to me pages in Confluence.
- Some pages appeared broken, with empty sections or code snippets. As we heavily used Confluence macros, this resulted in issues with proper display or incomplete migration of some content elements.
- We noticed different text colors, including blue and green, alongside the default black. However, the reasoning behind these color variations remained unclear.
- Our tagging system in Confluence required revision and rebuilding from scratch during the migration process.
- All images migrated but they were displayed with extra spacing or placed incorrectly.
Despite these issues, it is important to acknowledge that the automatic migration solution saved us a lot of time by avoiding manual copying and pasting, which could have taken us hours or even months.
Post-migration stage
Now, it’s time to focus on configuring the SharePoint site to suit our specific needs and leveraging its native features and customizations. We decided not to replicate our Confluence behaviors and, instead, embraced the capabilities that SharePoint offers.
Page hierarchy & navigation tree
One significant difference between Confluence and SharePoint is the approach to page hierarchy and navigation. Confluence follows a hierarchical structure, with pages and subpages automatically displayed in the navigation. SharePoint uses a different approach, with a single-page repository and libraries for documents, lists, and site assets. The navigation tree in SharePoint starts with a few default links but is customizable.
Page Tree, which came with WikiTraccs, served its purpose for the first days. However, from a long-term perspective, SharePoint’s native three-level mega menu offered greater flexibility (can include both internal and external links, as well as non-linked labels). It is worth noting that SharePoint’s limitation of only three levels (compared to unlimited levels in Confluence) can be frustrating at times. However, it raises the importance of proper information architecture.
Content look & feel
When it comes to creating a visually appealing experience, SharePoint offers a range of customization options.
- SharePoint site template. We chose the Department template because the landing page was closely aligned with our intended structure and layout. Additional pages coming with the template served as a great source of inspiration and a valuable reference.
- Theme. SharePoint does not allow a flexible color palette, so we just selected one of the predefined options that matched our brand and visual identity.
- Header and footer. We uploaded the necessary logo and selected the extended layout for the header. In the footer, we added useful links, copyright notices, and contact details.
- Page templates. We created a few page templates that we could later use as a basis for new pages. These templates include main elements to be used consistently, rules to follow, and samples to recreate. This ensured a cohesive and standardized layout for our content.
Sections & web parts
SharePoint offers sections and web parts as structural elements of the page, which allow effectively organize and present the content in a visually appealing and user-friendly manner.
Collapsible sections in SharePoint are particularly useful for long pages. They allow users to expand or collapse sections of content, improving readability and making it easier to navigate through extensive information. Another feature I appreciate is the ability to set background colors to group specific elements on a page, which helps create visual distinction and focus on important content.
The variety of SharePoint’s building blocks, aka web parts, is handy when it comes to presenting the content. Hero, Quick links, People, YouTube, Divider are just a few that we use a lot. These web parts allow us to showcase content in various formats, engage users with interactive elements, highlight key information, and create visually appealing layouts.
Access control
SharePoint provides granular access control and permissions management on a site level. It also allows users to define user roles and restrict access to specific content (pages or files). However, due to the absence of a parent-child relationship between pages in SharePoint, setting access restrictions for specific sections of a knowledge base can be challenging.
For the first release of a knowledge base on SharePoint, we decided to go with global site-level permissions and just a few page-level restrictions, which we will gradually fine-tune based on our specific needs and user roles.
Collaboration
Confluence has a lot of social collaboration features, such as likes, comments, and mentions, to facilitate discussions and engagement around content. With default SharePoint, it’s a bit limited. While SharePoint allows page commenting and tagging people in the comments, it lacks inline commenting, which is particularly useful when reviewing content or asking specific questions about a particular topic mentioned on a page. We will investigate options for fixing it in the next iterations though. There should be some add-ons to enhance collaboration capabilities. At least, I hope there are any😊.
Going live and the next steps
Even though we’ve already opened our new SharePoint site to our users, it does not mean our work is over. SharePoint is a robust platform with numerous features and capabilities that may be undiscovered. Every time I open site settings, it looks like we are just on the top of an iceberg, and a lot is still hidden from us. For example, we need to set up approval flows to streamline the technical writing and content review process. Content targeting is another promising feature, and this is something that we want to set up for the next releases. Tagging and metadata are on our radar for the upcoming releases too.
Overall, I must admit that I have mixed feelings about SharePoint. On the one hand, it offers a wide range of functionality and can be both exciting and challenging to work with. On the other hand, it doesn’t allow for easy collaboration or content reuse, which is critical for the Technical Communicator’s work. Well, let’s see how everything goes forward. It’s just the beginning.
Have you already worked with SharePoint as a knowledge base platform?
