docs: Iteration from Docs workshop.

* Bury Best Practices, for the time being.
* Bury Schema, but leave it on disk.
* Introduce new Querying section.
* Move "Why Apollo Server?" into "Index".
   * ...to be refined.
* Remove no-longer-helpful "Getting Started" from "Index".

cc @stubailo @evans @peggyrayzis @JakeDawkins @unicodeveloper @jbaxleyiii

docs/_config.yml

@@ -8,25 +8,13 @@ versions:
 sidebar_categories:
   null:
     - index
-    - why-apollo-server
     - getting-started
     - whats-new
   Essentials:
     - essentials/schema
     - essentials/server
     - essentials/data
-  Schema:
-    - schemas/organization
-    - schemas/types
-    - schemas/resolvers
-    - schemas/directives
-  Best Practices:
-    - best-practices/authentication
-    - best-practices/schema-design
-    - best-practices/performance
-    - best-practices/security
-    - best-practices/caching
-    - best-practices/monitoring
+    - essentials/querying
   Deployment:
     - deployment/index
     - deployment/heroku

docs/source/essentials/data.md

@@ -1,5 +1,5 @@
 ---
-title: Fetching data
+title: Fetching data with resolvers
 ---
 
 ## Overview

docs/source/essentials/querying.md

@@ -0,0 +1,45 @@
+---
+title: Sending queries
+---
+
+## Operation names
+
+When sending the queries and mutations in the above examples, we've used either `query { ... }` or `mutation { ... }` respectively.  While this is fine, and particularly convenient when running queries by hand, it makes sense to name the operation in order to quickly identify operations during debugging or to aggregate similar operations together for application performance metrics, for example, when using [Apollo Engine]() to monitor an API.
+
+Operations can be named by placing an identifier after the `query` or `mutation` keyword, as we've done with `HomeBookListing` here:
+
+```graphql
+query HomeBookListing {
+  getBooks {
+    title
+  }
+}
+```
+
+## Variables
+
+In the examples above, we've used static strings as values for both queries and mutations.  This is a great shortcut when running "one-off" operations, but GraphQL also provides the ability to pass variables as arguments and avoid the need for clients to dynamically manipulate operations at run-time.
+
+By defining a map of variables on the root `query` or `mutation` operation, which are sent from the client, variables can be used (and re-used) within the types and fields themselves.
+
+For example, with a slight change to the mutation we used in the previous step, we enable the client to pass `title` and `author` variables alongside the operation itself.  We can also provide defaults for those variables for when they aren't explicitly set:
+
+```graphql
+mutation HomeQuickAddBook($title: String, $author: String = "Anonymous") {
+  addBook(title: $title, author: $author) {
+    title
+  }
+}
+```
+
+GraphQL clients, like [Apollo Client](https://www.apollographql.com/docs/react/), take care of sending the variables to the server separate from the operation itself:
+
+```json
+{
+  "query": "...",
+  "variables": { "title": "Green Eggs and Ham", "author": "Dr. Seuss" }
+}
+```
+
+This functionality is also supported by tools like GraphQL Playground and GraphiQL.
+

docs/source/essentials/schema.md

@@ -1,6 +1,6 @@
 ---
-title: Building a GraphQL schema
-sidebar_title: Building a schema
+title: Understanding schema concepts
+sidebar_title: Schema concepts
 ---
 
 ## Overview
@@ -203,47 +203,6 @@ type Query {
 
 This makes SDL-generation even easier since many GraphQL tools auto-complete field names, along with the descriptions, when available.
 
-## Operation names
-
-When sending the queries and mutations in the above examples, we've used either `query { ... }` or `mutation { ... }` respectively.  While this is fine, and particularly convenient when running queries by hand, it makes sense to name the operation in order to quickly identify operations during debugging or to aggregate similar operations together for application performance metrics, for example, when using [Apollo Engine]() to monitor an API.
-
-Operations can be named by placing an identifier after the `query` or `mutation` keyword, as we've done with `HomeBookListing` here:
-
-```graphql
-query HomeBookListing {
-  getBooks {
-    title
-  }
-}
-```
-
-## Variables
-
-In the examples above, we've used static strings as values for both queries and mutations.  This is a great shortcut when running "one-off" operations, but GraphQL also provides the ability to pass variables as arguments and avoid the need for clients to dynamically manipulate operations at run-time.
-
-By defining a map of variables on the root `query` or `mutation` operation, which are sent from the client, variables can be used (and re-used) within the types and fields themselves.
-
-For example, with a slight change to the mutation we used in the previous step, we enable the client to pass `title` and `author` variables alongside the operation itself.  We can also provide defaults for those variables for when they aren't explicitly set:
-
-```graphql
-mutation HomeQuickAddBook($title: String, $author: String = "Anonymous") {
-  addBook(title: $title, author: $author) {
-    title
-  }
-}
-```
-
-GraphQL clients, like [Apollo Client](https://www.apollographql.com/docs/react/), take care of sending the variables to the server separate from the operation itself:
-
-```json
-{
-  "query": "...",
-  "variables": { "title": "Green Eggs and Ham", "author": "Dr. Seuss" }
-}
-```
-
-This functionality is also supported by tools like GraphQL Playground and GraphiQL.
-
 ## Next steps
 
 At this point, we hope to have explained the basic information necessary to understand a GraphQL schema.

docs/source/essentials/server.md

@@ -1,5 +1,5 @@
 ---
-title: Running a server
+title: Building a server
 ---
 
 ## Overview

docs/source/index.md

@@ -3,10 +3,13 @@ title: Introduction
 description: What is Apollo Server and what does it do?
 ---
 
+## Why GraphQL? Why Apollo Server?
+
 Apollo Server is the best way to build a production ready GraphQL server. It is designed from day one to make it easy to connect data from your backend(s) to a well designed schema ready for clients to use! Apollo Server is designed to work with every major Node HTTP servers such as Express, Hapi, and Koa, as well as serverless environments like AWS Lambda.
 
 Apollo Server supports the entire GraphQL Spec and can be queried from any GraphQL client. It's:
 
+
 1.  **Incrementally adoptable**, so you can drop it into an existing app today.
 2.  **Universally compatible**, so it works with any build setup, any GraphQL client, and any data source.
 3.  **Simple to get started with**, so you can start loading data right away and learn about advanced features later.
@@ -15,39 +18,6 @@ Apollo Server supports the entire GraphQL Spec and can be queried from any Graph
 
 These docs will help you go from getting started with Apollo to becoming an expert in no time!
 
-## Overview
-
-This documentation aims to provide a complete guide of how to build a GraphQL server by providing easy-to-understand overviews, in-depth guides and comprehensive best-practices.
-
-The documentation is organized with basic concepts and design decisions first and more advanced topics later on. Each section lists prerequisites needed to get the most out of it.
-
-After finishing, you will know:
-
-* Basic GraphQL concepts, in the server context
-* Why GraphQL is effective on the server
-* What requests a GraphQL server will receive
-  * Queries
-  * Mutations
-  * Advanced subscriptions
-* How a GraphQL server defines an API and creates responses to those requests
-* Best practices for designing a server
-  * Authentication
-  * Schema design
-  * etc.
-
-## Getting Started
-
-The docs for Apollo Server are mainly written using the [Express integration](./servers/express.html), but most of the examples work no matter what server library you use. The docs are broken into six distinct sections to make it easy to find your way around:
-
-1.  **Essentials**, which outlines everything you need to know in order to get started quickly
-2.  **Schema Development**, which goes over what a GraphQL schema is, and how to write one
-3.  **Running a Server**, which explains the mechanics of exposing your schema to clients
-4.  **Best Practices**, to explain the best possible way to build a GraphQL service
-5.  **Working with Backends**, so you can work with the data you have right away
-6.  **API**, to act as an entry point to find API details for key server libraries
-
-Getting started is as simple as installing a few libraries from npm! [Getting started](./getting-started.html) is a good place to start your adventure with Apollo Server!
-
 ## Productive GraphQL Development
 
 Apollo Server, and the rest of the Apollo ecosystem, give you a powerful set of tools to rapidly stand up a GraphQL API on top of your existing, or new, backends. It does this by focusing on a schema-first approach where you build your schema with a concise, declarative syntax, and fill in the logic with data fetching resolver functions. It is easy to get started with [one-step mocking]() while you fill out your data and build your UI. With powerful tools like [schema directives](./schemas/directives.html), [tracing and cache control](./best-practices/caching.html), and [schema stitching](), you can build the service of your dreams without writing a line of code more than you need.