Answer more FAQs in the docs

[jseldess]

As we identify more and more FAQs, we need a good way
to make answers to these questions easily accessible/searchable
in the docs. This PR offers one possible approach: Adding
an FAQs section to the sidenav, with categories of FAQs broken
into distinct pages. For example, in addition to the general
FAQ we've had for some time, I've added a page on SQL-specific
FAQs.

---

This change is 

[jseldess]

@sploiselle, @dianasaur323, @spencerkimball, @bdarnell, interested in your thoughts on this approach. I think it could suffice for a while, in the absence of a more traditional support-type "knowledge base".

An alternate approach would be to have each question and answer on its own page (much like in a support-style knowledge base), but perhaps we could consider that route when the FAQ pages get too long.

We were also talking about using StackOverflow and returning SO cockroachdb results in our docs search, but from what I can find, it's not going to be possible to do that well. SO can be great both for very niche questions as well as FAQs, and seems to me it doesn't hurt to have some redundancy in our docs.

[jseldess]

Also note that, in the near future, the CockroachDB in Comparison page will likely move out of docs, and we'll likely put architecture docs, which Sean is working on this quarter, somewhere else, too. So this FAQs section could eventually be exclusively devoted to FAQs.

[sploiselle]

Great thinking, @jseldess!

Think we could also solve the "knowledge base" problem you mention by using includes more aggressively. Think that could net us a few things:

• Ensures answers don't get out of sync (e.g. guidance around using interleaved tables)
• Optimizes for search/provides knowledge base-like behavior, while still letting us aggregate them on FAQ pages.

The only thing that gives me slight pause with it is that Google checks for duplicate content, so it might be worth testing this with a few of them and seeing how they behave before committing to the strategy full-on.

Thoughts on that?

[jseldess]

Excellent idea, @sploiselle. I've created an _includes/faq directory and already created examples of content that appears in an faq and in reference page.

How should we go about testing how Google responds to the includes?

[sploiselle]

Exciting you got this implemented so quickly.

For the pages that use shared content, I think we can monitor traffic from Google for a decline in the page views.

[jseldess]

OK, thanks, @sploiselle.

@dianasaur323, @jess-edwards, thoughts? One thing to point out is that, in this revision, I removed the "CockroachDB Features" pages from the sidenav. The pages are still there, they're just not listed in the sidenav. Figure those pages are going to be replaced by the product page as well as architecture pages that Sean is writing eventually anyway. But if there are objections, I can put them back in the sidenav.

[kuanluo]

Great idea, @jseldess @sploiselle!

One thought: Would be interesting to A/B test the placement of FAQ link in the nav. My eyes generally land on the first item and glance over the middle and land on the last item. Since FAQ does provide great value, a hypothesis is that by placing it at the bottom of the links, it will get more clicks. I don't have strong feelings about it, but would be cool to test.

[jseldess]

Let's go with your assumption, @kuanluo. I've moved FAQs to the bottom of the sidenav. If the content doesn't get enough traffic, we can think about doing A/B testing.

[dianasaur323]

The FAQs look good!

---

Review status: 0 of 9 files reviewed at latest revision, all discussions resolved.

---

Comments from Reviewable

[jseldess]

OK, for now, I'm putting the CockroachDB Features pages back in and merging the rest of these changes. We can remove the feature pages once it makes sense.

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/01e043dd26ceb36422572db97c89bfdefe2ef2f0/