doc: Searchable knowledge base

[msudberg]

As a user, I would like a searchable knowledge base with documents focused on troubleshooting and procedures.

Possibly we can use Zendesk for this.

[benesch]

Is there a reason that the "Operations" section in the current docs site is not a good fit for this kind of content?

[msudberg]

This came up in discussions with @morsapaes and @ruf-io because we were getting a lot of user questions about things that we do have documented, but that users either didn't bother to look for or couldn't find.

A knowledge base is generally focused on troubleshooting specific, very targeted problems and answers rather than giving general overviews and guidelines. There can be, and often is, a lot of overlap between knowledge bases and documentation, but the knowledge base is there for the most impatient and action-oriented users. It's also helpful in auto-generating a real FAQ, as opposed to "Things we think users are going to ask frequently before we launch", which is what most FAQs end up being.

[benesch]

Is a large chunk of this problem just that our current docs search engine isn't good enough to surface the content users are after?

[sploiselle]

I think that trying to get users to understand the difference between "documentation" and "knowledge base" misplaces the problem of finding content on the user, rather than the documentation/content team. I've seen this referred to as "shipping your org structure," which isn't apropos in this case, but illustrative of the problem. Making folks search two different places for content is not ideal UX.

A real solution to the problem of findability is to spend time analyzing your users' queries, tuning your search engine, and making sure people are properly shepherded into using your search feature.

[msudberg]

Users don't need to understand the difference between documentation and knowledge base; they just need to be able to search all applicable materials in the way that's easiest for them.

I don't think it's effective to design to the way you want users to interact with docs, as opposed to the ways they expect to interact with them.

[sploiselle]

I don't think it's effective to design to the way you want users to interact with docs, as opposed to the ways they expect to interact with them.

What does that mean?

[morsapaes]

Closing this issue as we are prioritizing a gradual restructure of the docs to make content easier to find and parse. There's also an open issue dedicated to improving our operational content (#9512).