Re-envision the docs site architecture

[jseldess]

For beta and 1.0, a single "docs" space made sense and remained more or less intuitive for users. As our content has grown, however, a single space is becoming insufficient for the range of content types we have or aim to have (guides/usage, cli/sql reference, demos/tutorials, architecture, support/faqs).

For 1.2, we should therefore research and implement a new structure that helps us divide (and scale) content meaningfully and, more importantly, makes it easier for users to find exactly what they need.

Examples:

• Kubernetes docs
• Google JavaScript API docs

In both of these cases, different types of content have been placed in different "spaces" of the docs site. Along these lines, a first proposal for CockroachDB is to decouple the docs site structure from the overall site structure. This would let us either replace the topnav or supplement the top nav with a secondary navigation like:

• Home
• Guides: get started, development, deployment, etc. This would be the bulk of our current content)
• Reference: this would be a separate space for dedicated cocroach command and SQL reference docs)
• Tutorials, or Demos: This would be a separate space for things like or "core features" tutorials, the cloud migration video, and other tutorials/demos that we should create.
• Support: This would be a separate space for knowledge base-like FAQs, which will become increasingly important as we get more clients and hire support staff. If we end up using ZenDesk or some other ticketing solution, there's an option to use that tools KB functionality and just integrate it with the site, though we may want to consider building this ourselves.

cc: @kuanluo

[jseldess]

cc also @nstewart, @dianasaur323, @robert-s-lee, @sploiselle, and @Amruta-Ranade for early thoughts as well.

[dianasaur323]

I think this is a great idea @jseldess. That is one of the things that I find hardest about navigating our current documentation. I would like to open up the possibility of grouping this by persona instead of by content type. I'm not saying that we should have "developers" and "dbas", but one concern I have is that some of our guides are clearly aimed for application development, while others are aimed for database management. I worry about grouping all of those guides together in one place. Beyond that though, I like what you've come up with so far, and would be comfortable with that approach as well.

[jseldess]

Good points, @dianasaur323. I agree with you that we should probably not display all guides to all users. I was actually imagining that, for example, once users choose "Guides", instead of showing them all in a sidenav, like we currently do, we could have a landing page where users could learn more about each guide and choose the right one. Same goes for some of the other categories. When you choose "Reference", for example, you might be able to choose whether you're interested in CLI reference or SQL reference or some other kind of reference we might come up with (REST API reference, for example, when/if we decide to document some of our public endpoints).

[dianasaur323]

Ah, yes yes. That would be awesome!

[sploiselle]

A clear-thinking way of understanding "Help content" from Divio:

Had a different comment here originally, but I'm realizing "Tutorials" here means content like our Getting Started Guides and feature demos.

[jseldess]

@kuanluo, @Amruta-Ranade, and I decided to focus on 3 tests:

Test 1: Current docs layout against a different layout of content

Current layout (everything in one place):

Alternate layout (content divided by type):

Docs home - with tiles introducing each section: Guides, Concepts, Reference, Support:

Just the guides, e.g., Getting Started, Development, Deployment, etc.:

Same idea for Concepts section, though it'll just have Architecture for now.

Just the reference content, e.g., SQL Reference and CLI Reference:

Support section, with our FAQs presented in a more knowledge base-style format:

Test 2: Current "guides" organization vs. organization by role

This is testing whether reducing our guides to Quickstart, Development, and Admin is helpful to users. Essentially, this combines a number of admin-esque sections (Deploy, Manage, Troubleshoot) into one.

Version 1:

Version2:

Test 3: Support area covering just our FAQs vs our FAQs + Forum + Stack Overflow

In version 2, the search would return not just our FAQs but also content from our community support channels.

Version 1:

Version 2 (very incomplete sketch):

[kuanluo]

Thanks for the writeup, @jseldess!

I mocked up two ideas for Test 1 with docs Home and Guide only. Both are fairly common approaches, and Option 2 gives the content a bit more room. In the example of the install page, subscribe box will appear before needing to scroll.

1. Preserve current main nav, and add secondary nav for docs.
   

2. Create docs-specific nav. Users have to click on the bug to return to the main site.
   

My main question is whether there are benefits to choose one or the other in our case. And first impression feedback welcome!

cc: @Amruta-Ranade @sploiselle

[jseldess]

@kuanluo, thanks for mocking this up so quickly! This looks great. Some initial thoughts:

1. Although I like the additional space gained by having on one main, docs-specific top nav, on thinking this through further, I think it's too early to make such a change. For now, we probably want the site-wide top nav to remain so as to make sure users can easily jump from docs to, say, the blog or the product pages.

2. I like the "home" page as you've designed it, but I think we might want to think about a few other configurations, for example, the four section options as well as an intro video.

3. Where do you think we should put the version selector?

[kuanluo]

Test 1

Agree with you on 1 & 2, @jseldess. The homepage was just one example of what it might look like - totally open to your ideas.

Where do you think we should put the version selector?

I'd imagine the version selector will only show up for Guides, and it will appear in the same place as it currently is, because the rest of the content (Reference, Support, etc) won't be updated via versioning. Thoughts?

Test 2

It's more of a content organization test, so instead of mocking it up, I wonder if it's just easier to do in code?

Test 3

I've been looking at how others do this, and think we need to think about the behavior through a it more. Your sketch seems to be a common design pattern when it comes to Support:

• https://support.stripe.com/ links from Docs, but an entirely separate page with different nav.
• https://docs.mesosphere.com/support/ funnels you through two options, and one of them leads to https://support.mesosphere.com/hc/en-us, which is also a separate page with nav.
• https://help.github.com/ Same thing, entirely different nav.

Is opening a new page with a separate something you have in mind? If we want to stick with the current company nav + docs subnav, perhaps we can do a simpler version of Support page for the next release to start, and go from there? Example below, and we can certainly make the other channels more prominent visually than bullet lists.

[kuanluo]

Notes from meeting with @j-low @jseldess

Test 1

• Version will be universal. I will do another pass on this.

Test 3

• For people who want support, search is very important allowing them to jump in and out. So we need to make it more prominent.
• From a development perspective, hiding search in the nav is easy. So it's achievable.
• Search results will show up on our site, and the links will be at Forum, SO, etc. And we need clear labels for sources.

Next steps

• I will revise the mocks, with mobile experience, by EOW
• @j-low and @jseldess will sync separately on execution for testing.

[kuanluo]

Versioning:

Option A: Same size as the secondary nav. Centering the nav:

Option B: A little smaller, left-aligned nav:

Support

I am not sure what content we're thinking of putting on the support landing page, just two ideas that make search obvious with supporting links.

Option A:

Option B:

@jseldess @j-low