The great divide, part 1: The case for separate knowledge bases

One of the common themes for people creating a knowledge base is the pursuit of a single source of truth, one system whose documentation you trust and use all the time. For most of us, that's what a knowledge base ends up being. But sometimes, circumstances may force you to create a separate knowledge base, such as a total content reorganization, a major new release, or mergers-and-acquisitions activities. They're valid reasons, but it can lead a good content creator to wonder: what's the best way to manage this?

This post is the first in a two-part series, where we're partnering with one of our customers to provide a case study of this one-becomes-two knowledge base scenario. Here, in part one, I'll lay out an overview of some of the ways we suggest our customers approach solving this problem, and the advice I gave to Scot Hanson at aACE Software when he asked me what to do.

In part two, you'll get Scot's actual experiences of how it all went and what his team would do differently next time.

The general use case

Knowledge bases can serve all kinds of purposes, whether they're sharing your internal policies and procedures in a consistent format for your entire company to access, providing your support staff with product or customer information, or providing your customers with product or service information. Despite these differences, the goal of implementing a knowledge base is often to provide a single source of truth for your documentation.

But there are times when that single source might stop being the best solution, such as:

• Undergoing a major rebranding or content reorganization
  In these cases, the new knowledge base might be a temporary testing ground or may become the "new" single source of truth. This scenario is more of a temporary separation to make it easier to work toward that goal.
• Spinning off a product or company
  Creating a separate knowledge base is a necessary first step to disentangling the content and intellectual property of one product or company from another.
  
• Adding a brand new product or company to your portfolio
  Maintaining the new product or company's separate identity might be important for legal reasons, branding, or logistics such as differing regions or languages. Perhaps the customer base of your differing products has no real chance of overlap, so having everything in one place would create too much noise or information overload.
• Adding knowledge base content in a different language
  In some cases, having content in multiple languages in the same knowledge base can be confusing or highly complicated (such as trying to combine content written in right-to-left and left-to-write languages). In this case, separate knowledge bases can let you optimize each knowledge base for linguistic and cultural norms--or simply to keep it easier to maintain the content working with different translators.
• Creating a major new release of your product or service
  While many updates can be handled within the same knowledge base, really sharp or overarching changes might be better handled in a separate knowledge base--especially if your product is installed, the upgrade process requires your support team's assistance, or the menus and terminology are wildly different. While this scenario can sometimes be handled through rearchitecting your existing knowledge base, there are times when it pays to not move people's cheese. 🧀
• When your knowledge base is trying to serve too many purposes for too many different audiences
  A knowledge base is often created for a specific team or to solve a specific problem (such as streamlining help desk operations or providing product support). Over time, additional departments, regions, teams, or products might be added. While this does create a single overarching source of truth, different groups might use and structure their corner of the knowledge base differently. It may make more sense to separate this content into one or more additional knowledge bases to keep your content creation and usage patterns as simplified as possible.

None of these scenarios requires that you add another knowledge base--but sometimes it can make life easier.

Our use case

aACE (as in Accounting, Customer relationship management, and Enterprise resource management) Software is an end-to-end suite for business operations software. Designed for small to mid-sized companies, it helps staff get work done and helps management keep track of what needs to be done.

aACE is an installed software product. Scot Hanson, their lead technical writer, has been using KnowledgeOwl to host its software product user guides since 2017, when they migrated from Zendesk. Each installed version of aACE includes a hyperlink on the aACE main menu to direct users to the knowledge base.

This year, aACE is delivering a major software release, from version 5 (v5) to version 6 (v6). Scot had a few reasons for wanting the v6 user guides to live in their own knowledge base separate from v5:

...we anticipate having our current v5 customers clinging to that version for a long time. We have some older customers who have been using v4 since 2015. They're slow to upgrade because v4 works so well already and they've got customizations in place to streamline their workflows. So we've left the v4 help guides published in case they need to access them. Going forward, instead of trying to keep 2 knowledge bases updated, we'll just let the v5 knowledge base sit as-is, focusing our attention on updating the v6 knowledge base.

In March, Scot reached out to ask for our input. He already knew he wanted the separate knowledge base for v6. The question was: what was the best way to take the copy and then facilitate getting the v6 content actually updated to v6?

Suggested workflow

Scot's inquiry was basically two-fold:

• Was it better to copy the entire knowledge base, or copy individual articles/categories?
• How could they manage the update process--could a note or some other metadata be added to those copies so they knew they hadn't been updated yet?

The copy: Go big

After discussing the situation in more detail, we decided that taking a copy of their current knowledge base made the most sense, rather than copying individual pieces of content. The overall content hierarchy wasn't going to change much, so it was easier to copy everything and update the copies to v6 rather than manually copying individual articles and re-creating the category structure.

Yes, you can copy your own knowledge base with no assistance from our support team, if you desire. 😉

How to manage the content update

When Scot first reached out, he asked if we had some way to add a note to all the articles that had been copied over. While we potentially could have scripted adding an Internal Note to all the articles in the copied knowledge base via API, I shied away from this approach. Internal notes are a free-form text field, and while you can put a lot in there, they're not easy to access in bulk.

I felt a tag-based approach combined with a publishing status change would make it easier.

To help facilitate the update workflow, Scot would bulk edit all the articles in the v6 copy to have an "aACE 6" tag and set them to the "Ready to Publish" status. Then he and the interns would work through all of the content there to update it to match version 6 of the software, updating the publishing status and removing the tag as they went.

The summary plan I sent him looked a bit like this:

1. Purchase additional knowledge base (KB) slot for Version 6 (v6) documentation.
2. Use gear icon on dashboard and select "Copy" to create v6 KB with copies of all existing content.
3. In v6 KB, Manage Articles > Bulk Edit to add "aACE 6" tag and set "Ready to Publish" publishing status.
4. Set up KnowledgeOwl user accounts for the 2 part-time tech writing interns who were assisting Scot.
5. With assistants, review each v6 article and update content.
6. Remove tag and update status to Published as each v6 article is updated.
7. Celebrate with doc update party. Owls for everyone! 🦉
8. Eventually...delete/sunset the Version 5 docs and remove the extra KB slot at that time to save money.

Step 8 is optimistic on my part--we all know how hard it can be to get every last customer off of an older version of software. But ultimately that is the goal!

Rationale for this approach

This approach has some limitations and considerations. Let's walk through those and why I suggested this path forward for aACE.

Copies aren't perfect replicas

Copying a knowledge base will copy the bulk of the content, but there are a few things it doesn't handle well:

• It removes Related Articles.
• It removes any Shared Content relationships.
• It doesn't copy the entire File Library; the new knowledge base simply points to the files stored in the old File Library, which can make file audits tricky.

None of these issues was a dealbreaker for Scot.

By his own admission, he hadn't made heavy use of related articles or shared content articles, so he wouldn't be impacted by the first two points.

And the File Library ownership was a non-issue: the content updates for v6 would require updating every single screenshot and file. In this case, it actually helped keep the File Library tidier in v6, since it would only contain all the new screenshots!

Manage Articles filters are your friend

I use Manage Articles functionality for a lot of audit- and update-related work, since it allows you to bulk edit articles and you can create and save filters based on all kinds of criteria. In this case, Manage Articles is explicitly mentioned in Step 3 for the bulk edit, but I also suggested using it for Step 5, to make it easier to keep track of what still needed updating.

At the time, I suggested that Scot:

instruct each assistant to create a Manage Articles filter that looks for that Ready to Publish publishing status and aACE 6 tag, so they can work from a list of "still needing updates" and see it get smaller. That helps people not step on each other's toes and gives you a clear measure of how much progress you're making, since you can compare tallies on the filter from week to week.

I use this feature in Manage Articles a lot for audits or massive content updates, creating Manage Filters that look for a particular tag, author, or other details. It's much easier than navigating through the content hierarchy, since it lists out only the articles that match the filter. It's also a lot more gratifying to watch the number get smaller and smaller as you update content and remove the tag or status that put it there. 😉

Final thoughts

As I mentioned at the start of this post, this is the first in a two-part series. In part two, Scot will share with us how it all went. (The exact format of this is still to be determined, since we've not done one of these before. Maybe I'll interview him. Maybe he'll write the whole thing and I can just offer color commentary in parenthetical asides. Who knows!)

I'm curious to see if this approach worked for the team at aACE, what changes or improvements they made, and what the team wishes they might have done differently. Their original timeline was to have everything done by August 31st. Our goal is to have the second post in this series published in October. Stay tuned!

To see how aACE helps small and mid-sized businesses compete and grow, including customer case studies and detailed highlights for specific features, please check out their website. You can also go poke around their v5 user guides if you'd like to see how they're set up!