Does this live in the docs or on the knowledge base?

You may also be interested in my thoughts on content living on a blog vs docs

Making customers successful with a product requires three key components:

1. UX: If the application is intuitive, customers are successful without thinking about it.
2. Documentation: Practically speaking, most apps need supporting documentation to explain new concepts or provide concrete implementation instructions.
3. Support: Heroes that work directly with customers every day to make them successful in a 1:1 setting.

Great UX is the ideal solution, but in most companies, customers need supporting enablement content.

As the company grows, both the documentation and support teams build out their own libraries of content to make customers successful. Eventually, they’ll hit a critical mass and someone asks the inevitable question:

Does this live in the docs or on the knowledge base?

Both teams want their content to live in their own system. Support wants to use the knowledge base as it has deep integration with their ticketing system, with workflows for pulling answers from articles which aren’t always able to integrate with external docs. Docs want to use their docs-as-code platform and all the tooling that they’ve built around the written word.

Where does the content live?

Whatever you do, don't store the content in both places. The second copy goes out of sync before you even hit publish.

Instead, categorise content in two buckets:

• This is generally applicable to the majority of customers using this product
• This is specific to a small number of customer setups

Imagine that you have a customer issue come in and the support team resolves it. Now what? Where does the solution go?

If the answer applies to the majority of customers, then I recommend having a small KB article so that it shows up in their day to day workflow, but the KB article has a small description that then links to docs.

If the answer is specific to a small number of customers, the answer lives in the KB. The support team shares these answers on demand in response to tickets. They're also available if people search the KB specifically (or on the docs too if you have multi-site indexing).

Splitting content by audience allows you to keep your documentation focused on the 80% of customers that can be successful without human interaction. Providing an exhaustive list of failure modes makes it difficult for customers to find what they're looking for when everything is working as expected.

Examples

The above is quite abstract, so here are some examples from the docs teams that I’ve been a part of.

Vonage provides communication APIs, including SMS. Sending an SMS using the API is something that was applicable to everyone, so it had public docs. Restrictions around the sender ID (from) used are different on a per-country basis (Peru for example). Most of Vonage’s customers were in the USA where there were no restrictions, so this information lived in the knowledge base. When the USA introduced 10DLC it affected the majority of customers, so the restrictions were added to the public docs and the knowledge base.

Kong provides connectivity tools, such as API Gateways and Service Meshes. Older versions of Ubuntu don’t have a required library (zlib) installed by default and every customer using an old version of Ubuntu encounters this issue, so we document it on the installation page. Kong Mesh allows you to proxy requests to Redis, but sometimes you get a cryptic "Error: Protocol error, got "H" error. This means that you configured your MeshGatewayRoute as with a HTTP protocol rather than TCP. A small percentage of customers hit this issue, so it lives in the knowledge base.

TL;DR

1. If it’s applicable to > 50% of customers, put it in the public docs
2. If it applies to a small percentage of customers, put it in the knowledge base
3. Make the support team’s life easier by putting pointers to public docs in the knowledge base