Product Documentation vs. Knowledge Base

Determining the right location for information is one of the fundamental problems faced by application developers, technical writers, and customer support engineers. It’s no good having information that no one can find, and the first step in making sure your users find it is putting it somewhere they’re likely to look. At Stormpath, we’ve got two places where information lives: our product documentation and our knowledge base. These two live in different places, are largely maintained by different teams, and until recently, also contained a lot of the same information. This isn’t just a Stormpath problem; it’s something that crops up very often as a company grows.

The overlap caused no end of confusion for customers and employees alike, as they might find the same information on two different pages explained in two different ways by two different people. It was also a maintenance nightmare since any update had to start with you finding all the places that something was documented in the first place.

Technical Product Documentation

Our product documentation lives separately for a number of reasons. First, the product team wanted to build multiple product guides, with custom code, pre-processors, if-then-else logic, and so on. All of this was possible with a combination of markup and static-site generators, but not possible with Zendesk.

Secondly, we wanted consistency with the code documentation. A lot of our language-specific API documentation is generated out of the code using tools like Javadocs and Sphinx. It’s easy to make this documentation look and feel consistent using static-site generators.

Finally, on a team of mostly developers, there’s an understandable preference for markup and plain text over a Zendesk, Wordpress, etc. WYSWYG interface.

Having established why we wanted separate product documentation, we came up with these goals and standards for it:

• Product documentation is built around product functionality (i.e., it’s proactive).
• The structure represents how a developer would actually need to learn about Stormpath and think about their own project. You could (if you wish) read it end-to-end.
• It strives to cover all product functionality, but no more.
• Every feature should be documented, even if it's rarely used.
• Doesn’t discuss external systems or integrations unless they are an official part of the product (i.e., no “unofficial workarounds”).

What does or doesn’t belong in there is usually a game-time decision by the product team, but in general, workarounds, specific instructions on using Stormpath with non-Stormpath tools or libraries, and short answers to specific questions all do not belong in product documentation.

Customer Support Led Knowledge Base

The knowledge base (KB) is maintained by the customer support team, who work out of Zendesk. Zendesk came equipped with a KB feature, and it’s very nicely integrated into their question submission workflows. This means that if a customer wants to ask a question, they can be shown relevant KB articles. At the same time, Zendesk also provides search results to the Customer Success team when they’re answering a question, saving time that would otherwise be spent writing redundant answers. Sounds great, right?

Of course, what many teams quickly realize is that the road from a customer question to documentation is not at all straightforward. How can you tell if a customer’s question should be forwarded to the product team and added to the documentation queue or whether a simple KB article will do?

So, when we set about defining what rightly belongs in our knowledge base, this is what we came up with:

• The KB is built around customer inquiries (i.e., it’s reactive).
• Its focus is troubleshooting.
• KB article topics come from common customer questions whose answers don’t belong in the product documentation (see above).
• Every article is structured around a problem and a solution.

Every knowledge base should aim to help a customer with a specific problem get an answer as quickly as possible.

This is all of course still evolving, but we’re happy with the division we’ve arrived at. Product documentation aims to be comprehensive, structured, and accurate. Everything that you would want from the canonical source of information for your product. The knowledge base doesn’t aim to be comprehensive, it contains little to no structure in and of itself, and the articles are short and to the point.

The next goal is ensuring that customers are able to find the information in both sources as quickly and intuitively as possible. The knowledge management challenges never end!

Questions? Opinions? Leave them in the comments below, and don’t forget to check out my post on why video documentation is never the right answer!