Proposal for a new sidebar organisation for sql docs.

[knz]

This PR forks off #1008.

This is a proposal to initiate a discussion about the structure of the sidebar.

The motivation from this stems from the observation that the sidebar is hard to navigate in the "develop" section and fails to identify the hierarchical nature of how developers approach documentation about a new programming environment.

The proposal approaches this by defining the following top sections:

• Writing SQL queries (About the SQL language as supported by CockroachDB)
• Using transactions (About how the SQL queries are handled server-side)
• Data definition (About how to organize data)
• Misc: Security ("Privileges" in proposal) and Client Sessions (not yet written, but will need to be)

It further separates the language features that belong to each of these categories. The classification is "clean" in that it partitions the entire set of SQL statements along these lines without overlap (with one exception, "CREATE TABLE AS" which is really "CREATE TABLE" combined with "INSERT" and is a non-standard extension).

---

This change is 

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/5184f496fce1ef86c96604f846455366f2f11dc4/

[knz]

Note that regardless of what you think the sidebar I would recommend adopting this structuring of sql-statements.md nonetheless, as it makes its reading much more pleasant.

[maddyblue]

Three levels of sidebar gets visually unpleasant. I like the idea of this change, but kind of wish we would remove the sidebar completely and adopt a new method of navigation, and then do changes like this.

[knz]

What I'd like is a proper book structure with parts, chapters and sections. Ultimately we ought to produce a single PDF with the whole. I am not too attached to the sidebar, but until we have a proper table of contents and navigation items (like prev/next section buttons) we need to do something about it.

[bdarnell]

I agree with @mjibson, three levels of sidebar navigation is too much for these common pages, especially when the sidebar collapses again when you navigate. I like the proposed grouping of SQL statements but I'd prefer to combine this with lifting the whole "SQL Statements" subtree up to the top level (I still have to stop and think for a moment to locate this section under the "Develop" heading).

[jseldess]

As mentioned to @knz in another thread, I think the direction of these changes are great, but I'm a bit concerned about tackling too much of this this quarter, for a few reason:

1. To properly rethink the architecture, and possibly move away from a sidebar, we need Design (@kuanluo) to help us plan and test for that, ideally with actual users, so as to get away from our own biases. But site re-architecting isn't in scope for Design or Docs for Q1. Likely Q2.
2. @mjibson is planning to migrate docs from Jekyll to Hugo along with the Wordpress portion of the site. That'll free us up to put in place an actual site/url structure (right now, everything's flat).

Here's what I propose:

1. We come up with a short-term fix to raise SQL to the top level (building off of the changes @knz has here).
2. In migrating to Hugo, Matt keeps the docs hierarchy flat for now. If we build in a url hierarchy with the move and then change the hierarchy again with our re-architecting, that's a lot of headache for us and users (lots of redirects).
3. We start planning a larger overhaul of the site structure, to be continued, tested, and implemented in Q2.

Thoughts all, especially @kuanluo and @mjibson, since this alters the migration plan for this quarter?

[maddyblue]

That sounds ok to me. I don't think a jekyll -> hugo conversion will take long. There are programs that automate most of it already.

[sploiselle]

My thoughts echo @jseldess; to do this effectively, we need to engage design and make data-driven decisions about restructuring the site and its navigation. Before signing up for any major restructure, I need data validating its efficacy vs. other possibilities. This specific restructure, though, is definitely worth including in those tests.

[jseldess]

Closing this for now. We should reference the ideas and conversation here once we prioritize reworking the docs info architecture.