A real-life scenario: We have to use a knowledge base tool for product docs

Your organisation has selected Zendesk / HubSpot / ServiceNow / some other tool as the new service desk environment, and you’ve been told the product documentation has to be done in there too. If you can manage a knowledge base in there, you can manage the product documentation too: what’s the difference? It’s all just documentation, right?  

But the team who look after the product documentation are used to sophisticated features for maintaining documentation, and knowledge base tools don’t have these capabilities. What does all this mean for the future of the product documentation? 

Common causes 

How does this situation come about? We see several common reasons.

User experience is often the main driver for this decision: 

• Product information is scattered around multiple repositories. Collecting everything in the same knowledge base means people don’t have to spend so much time working out where to look. 
• Product docs are still delivered as PDF – often via email – and everyone agrees they need to be accessible online. 

Perceived ease of implementation: 

• Knowledge base tools offer an easy way to build a docs  portal, complete with built-in AI chat-style search, and good features for managing user access (it’s already aligned to product access via SSO) and tracking analytics. All the things the organisation wants for their docs portal, and conveniently packaged up in the same tool that’s been selected for managing service requests! 

Gaps in understanding of the challenges of maintaining product documentation:  

• Decision-makers are unaware of some of the factors that are very different from knowledge base articles or FAQs:  
  • higher volumes of content 
  • managing documentation to align to multiple versions or variants of a product 
  • drafting the next interconnected set of updates over several weeks or months – whilst also maintaining the current docs 
  • reusing the same pieces of information across user docs, admin docs, and training materials (preferably without duplicating maintenance effort by copying and pasting) 
  • link management, review cycles, audit trails, automated QA …
• There are workarounds for all of these in a knowledge base tool, but relying on them is like eating ice cream with a knife: you can do it, but it’s not the best tool for the job.

Solution 

1. Check you really do have to use the knowledge base tool for everything. 

Before you go any further, ask whether the knowledge base is really the right home for all of your documentation. It may be that the business requirement is that everything has to be consumed by your customers that way. In which case, it may still be possible to create and maintain the information in the current tools, and then make use of APIs or integrations to deliver the docs via the knowledge base. Or perhaps it would even be enough to connect the knowledge base API agent to your current docs repository? Setting this type of integration up isn’t trivial – but neither is migrating a whole set of information from one tool to another, so it may be the more efficient option. 

2. Plan your migration. 

Assuming the knowledge base tool is going to be the future tool for creating and maintaining product documentation, you’ll need to think about: 

• Information model. We often see teams migrating-in their current docs one by one. The result: a load of duplication, tangled information architecture … terrible UX and an unreliable source for AI search or chat tools. Particularly if you are currently managing multiple documents per product (installation guide, user guide, quick start…), rather than a help site or docs portal. Instead, design the future information model and information architecture and map your current documentation onto it: what content types are going to work as articles? What information will they contain, and how will they relate to other articles about the same product? That way you’ll know where everything should land … and if maybe you’ll even find you can retire some of your current content. 

• Technical migration workflow. If the new tool has good support for import, there may not be a lot to do here once you’ve mapped current content into future articles. But many don’t, so you’ll need to think about what you can do to automate as much as possible. Expect to need to deal with broken cross-references, lost graphics, and complex styling that isn’t supported in the target tool (nested bullets and numbered lists are a common pain point!). 
• Documentation processes. Review your current processes around drafting, reviewing and publishing documentation. Decide how you’ll adapt in future, and what it will mean for how you work with other stakeholders to create and maintain product documentation. There may actually be opportunities here to improve some aspects of your current workflow. While these tools don’t have the same capabilities as specialist documentation tools, they’ve typically been very fast at introducing AI features to support content creation – for example, comparing an existing version of an article with new input, and using that to draft updates.  
• Manage expectations. As with any change, people need to know what’s going on. From our experience, people often have unrealistic expectations about the speed of migrating from one toolset to another. This is more likely to be a six-month project than a one-month project, and you’re probably also keeping documentation up to date with product changes at the same time. So set out your phases clearly in a roadmap – from MVP to fully operational – and prepare everyone to accept compromises along the way. 

3. Prototype, and then migrate in phases. 

Unless you have access to a lot of extra resources, don’t be too ambitious about what you try to achieve in each phase: pick just one type of content or one product. If you try to simultaneously migrate, improve and update to match a product release, it’s likely to result in the whole process grinding to a halt. 

Outcome 

Product documentation can be maintained and delivered in a knowledge base tool, but it’s going to come with compromises. Once things settle down, you’ll be able to assess the limitations – and perhaps also the advantages. And from here, your future plans can focus around making best use of the possibilities of this new tool.