docs(cookbook/graphql): full first editorial pass

Author: kapunahelewong

public/docs/ts/latest/cookbook/graphql.jade

@@ -412,8 +412,10 @@ code-example(language="sh" class="code-shell").
 
 .l-sub-section
   :marked
-    You can look at it as the equivalent of POST request in REST
+    You can look at it as the equivalent of a POST request in REST.
 :marked
+  GraphQL mutations, like queries, are straightforward with minimal syntax. 
+  Consider this example of a mutation:
 code-example(language="json").
   mutation {
     addHero(heroName: "Russell Brand") {
@@ -422,12 +424,16 @@ code-example(language="json").
     }
   }
 :marked
-  GraphQL mutations consist of two parts:
-  1. The mutation name with arguments (`addHero`), which represents the actual operation to be done on the server (just like calling a function)
-  2. The fields you want back from the result of the mutation to update the client (`id` and `name`) - which is very powerful - You, as the client developer can
-  decide which fields you will get back, not something that the server will dictate for you
+  First, you declare that you're writing a mutation and then specify what it does. 
+  To break it down, GraphQL mutations consist of two parts:
+  1. The mutation name with arguments (`addHero`), which represents the actual 
+  operation to be done on the server (just like calling a function).
+  2. The fields you want back from the result of the mutation. These update the client. 
+  In this example, they are `id` and `name`. This allows you to decide 
+  which fields you get back from the server, 
+  rather than the server dictating what's returned.
 
-  The result of the above mutation might be be:
+  The result of the above mutation might be:
 code-example(language="json").
   {
     "data": {
@@ -439,20 +445,50 @@ code-example(language="json").
   }
 .l-sub-section
   :marked
-    You can get deep into the mutation syntax on the [GraphQL.org website](http://graphql.org/learn/queries/#mutations)
+    For an in-depth look at mutation syntax, see the [Mutations 
+    documentation](http://graphql.org/learn/queries/#mutations) 
+    at [GraphQL.org](http://graphql.org).
 :marked
-  So first let's add a local function to add a hero to our template:
+  To use a mutation, first update the template with a function to add a hero:
 +makeExample('heroes-graphql/ts/src/app/heroes.component.html', 'add', 'heroes.component.html')
 :marked
-  and component:
+  In the component class, create the `add()` function. It expects a name argument of type `string` 
+  and is `void` because it returns nothing.  
 +makeExample('heroes-graphql/ts/src/app/heroes.component.1.ts', 'add', 'heroes.component.ts')
 :marked
-  and now let's add an `addHero` mutation to that function using the `apollo.mutate` function:
+  Now for the fun part. Inside of the `add()` function, add an `addHero` mutation 
+  using the `apollo.mutate` function as follows:
 +makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'add-mutation', 'heroes.component.ts')
 :marked
-  You can see, that our mutation requires and variable and we pass it to the `mutate` function through the `variables` param.
+  The mutation requires and variable and we pass it to the `mutate` function through the `variables` param.
+.alert.is-important
+  :marked
+    Uri: Could you explain this above segment section by section? 
+    You've already explained the part in green, so you shouldn't 
+    have to say much about it. The rest, though, could benefit from 
+    a little guiding prose. Two or 
+    three short paragraphs should be fine. We just want the reader to 
+    understand at least the gist of what each part of the code we give 
+    them is doing. I'd explain these but have only the vaguest notion 
+    of what's going on. Pretend you are explaining it to me. I don't know what 
+    the tick marks are doing (are they like a template string?). I have a cursory understanding 
+    of what an observable is...I see we are pushing the `id` and `name` but
+    don't quite understand how/when. The subscribe syntax loses me. Lastly, 
+    I don't know why we are setting the `selectedHero` to `null`.
+
+:marked
+  Just like a query, the mutate function returns an Observable you can subscribe to 
+  that handles the data you request.
 
-  Also, just like a query, the mutate function returns an Observable we can subscribe to and handle the data we asked for.
+.alert.is-important
+  :marked
+    Uri: Let's say something here about how we can now add a hero. Can the 
+    reader now click their add button and their new hero be added? Can we 
+    show this in a gif or a screenshot? Showing the achievement could 
+    make the point about how beneficial GraphQL is very quickly. 
+    Imagine the reader coming to this page and giving it a cursory scroll 
+    to see how long it is in deciding whether or not to work through it. 
+    A gif (especially) or screenshot could help them decide to do it.
 
 .l-main-section
 <a id="resources"></a>
@@ -479,79 +515,163 @@ code-example(language="json").
 :marked
   ## Appendix: Setting up a GraphQL server
 
-  We are going to show you how to add a GraphQL server in Javascript.
+  Running the server in the browser helps you start using 
+  GraphQL on your frontend without having a GraphQL backend. 
+  If you don't have the option of running GraphQL on the server, 
+  this method makes it easier to handle multiple REST 
+  requests and join logic on the client.
 
-  Like the other examples on angular.io, we are going to run the server in the browser as part of our Angular app,
-  it's good for testing and also if you want to start using GraphQL on your frontend without having a GraphQL backend.
+.alert.is-important
+  :marked
+    Uri: Can you tell me why it makes it easier? We should say 
+    "...logic on the client because..."
 
 .l-sub-section
   :marked
-    You can learn how to run a full GraphQL backend on the [Apollo Server docs](http://dev.apollodata.com/tools/).
-    The good thing is, that because it's Isomorphic Javascript, it is almost identical to the simple server we will run inside our Angular app
-    so everything we'll learn now will be the same when you would want to move to write a GraphQL backend.
+    To read more about how to run a full GraphQL backend, see the [Apollo Server documentation](http://dev.apollodata.com/tools/).
+    Because the real, backend server is written in Isomorphic Javascript, 
+    it is almost identical to the local server in this appendix.
+    Everything you learn here applies to writing an actual GraphQL backend server.
 
-    Also, there are few GraphQL based Backend-as-a-service platforms out there, like Firebase but based on GraphQL API, to help get
-    started really fast - https://www.scaphold.io/ https://www.graph.cool/
-:marked
-  To start, let's create a file called `in-memory-graphql.ts` inside our Angular app.
+    Additionally, there are a few GraphQL based backend-as-a-service platforms available, 
+    such as Firebase, but they are based on the GraphQL API.  For help on getting
+    up and running, see [Scaphold](https://www.scaphold.io/) and [Graphcool](https://www.graph.cool/).
 
-  First thing we should do is to create our GraphQL schema.
+.alert.is-important
+  :marked
+    Uri: Can you explain why the GraphQL API makes using things like Firebase different? 
+    There's a "but" in that sentence, but I don't know what it implies.
+
+:marked
+  In order to create a GraphQL schema, you need the `graphql-tools` library.
+  It allows you to write a GraphQL schema as a string and make it executable. 
+  In a terminal window, issue the following command:
 
-  For that we will use the `graphql-tools` library that let's us write a GraphQL schema as a string and make it executable:
 code-example(language="sh" class="code-shell").
     npm install graphql-tools --save
+
 :marked
-  Now for the schema itself:
-+makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'graphql-schema', 'Heroes GraphQL Schema')
+  Next, create a file called `in-memory-graphql.ts` in the `app` directory 
+  and paste in the following schema:
+
++makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'graphql-schema', 'in-memory-graphql.ts')
+
+.alert.is-important
+  :marked
+    Uri: Could you change the use of "we" in the above comments to "you" or the imperative (command without 
+    "you")?
 .l-sub-section
   :marked
-    The schema is pretty self explanatory, but if you want to dig deeper, check out [GraphQL.org `learn` section](http://graphql.org/learn/)
+    While the schema includes the major points covered in this cookbook, 
+    you can read more in the [GraphQL.org Introduction to GraphQL](http://graphql.org/learn/).
 :marked
-  Next let's create our in-memory data:
-+makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'heroes-array', 'Heroes Array')
+  Now, create your in-memory data:
++makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'heroes-array', 'in-memory-graphql.ts')
 :marked
-  Now we need to write a server that will resolve the queries that we will get from the client based on the schema.
+  The next step is writing a server that _resolves_ 
+  the queries from the client based on the schema. 
+  Hence, the GraphQL server consists of _resolver 
+  functions_ that correspond to the _types_ of the schema.
+
+  To create the resolvers, copy the following code and add it to `in-memory-graphql.ts`.
++makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'resolvers', 'in-memory-graphql.ts')
 
-  The GraphQL server consists of resolver functions that correspond to the types of the schema.
 .l-sub-section
   :marked
-    For the full explanation about how GraphQL resolvers work check out the [execution section](http://graphql.org/learn/execution/) of GraphQL.org
-:marked
-  Let's create our resolvers:
-+makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'resolvers', 'Resolvers')
+    For the full explanation about how GraphQL resolvers work see
+    [Execution](http://graphql.org/learn/execution/) on [GraphQL.org](http://graphql.org/).
+
 :marked
-  We also used some functions from `lodash` so don't forget to install them from npm and import them:
-+makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'import-lodash', 'Importing lodash')
+  You may have noticed some functions from `lodash` such as `lodashFind()` so don't 
+  forget to install them from npm and import them:
++makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'import-lodash', 'in-memory-graphql.ts (imports)')
+
+.alert.is-important
+  :marked
+    Uri: What is the npm install command for the lodash functions? 
+    Do we install the whole lodash library or just the functions? 
+    (I've never used lodash before).
+
+
 :marked
-  As you can see, we created functions that correspond to each type of our schema and also to the mutations.
+  Notice that the server includes functions that correspond to each 
+  type in the schema _and_ the mutations.
 
-  This mechanism makes writing simple GraphQL servers very easy, you simply think about how to resolve a specific type of data,
-  separates the frontend logic from the backend, removing the coupling between frontend and backend.
+  This mechanism makes writing simple GraphQL servers straightforward&mdash;you simply 
+  resolve a specific type of data. 
+  This removes the coupling between frontend and backend.
 
-.l-sub-section
+.alert.is-important
   :marked
-    Also in case you don't have the option to run GraphQL on the server, it's much easier to handle multiple REST requests and join logic on the client using these tools
+    Uri: I don't know how to incorporate this: "separate the 
+    frontend logic from the backend". And I don't know if 
+    I'm right about "This removes the coupling between frontend and backend".
+    I was trying to make it clearer by breaking it into smaller ideas, but 
+    I'm not sure what those ideas should be.
+
 :marked
-  Now we need to connect the shema to the resolvers with the `makeExecutableSchema` function from
+  Now, connect the schema to the resolvers with the `makeExecutableSchema` function from
   the [graphql-tools](http://dev.apollodata.com/tools/graphql-tools/index.html) library:
-+makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'import-graphql-tools', 'importing graphql-tools')
-+makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'make-executable-schema', 'makeExecutableSchema')
++makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'import-graphql-tools', 'in-memory-graphql.ts (excerpt)')
++makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'make-executable-schema', 'in-memory-graphql.ts (excerpt)')
+
+:marked
+  In the constant `schema`, `makeExecutableSchema` has two properties, 
+  `typeDefs` and `resolvers`. Here, you define them with the `typeDefinitions` 
+  and `resolveFunctions` that you created earlier in `in-memory-graphql.ts`. 
+  This way, your app/GraphQL? (Uri - can you correct me here?) knows where to look 
+  for definitions and resolvers.
+
+:marked
+  Now that you have an executable schema, execute it using the `graphql` 
+  library and export it so you can use it with the Apollo Client. 
+  First, `npm install`:
+
+.alert.is-important
+  :marked
+    Uri: can you provide the npm install command?
+
 :marked
-  Now that we have executable schema, let's execute it using the `graphql` library and export it so we can use it in our Apollo Client:
-+makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'import-graphql', 'Dont forget to npm install')
-+makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'execute-and-export', 'Execute and export')
+  Next, add an import statement for `execute`.
+
++makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'import-graphql', 'in-memory-graphql.ts (excerpt)')
+
+.alert.is-important
+  :marked
+    Uri: Could you explain what's happening in the below? 
+    This will probably take 2-3 short paragraphs. Just a 
+    general tour from top to bottom.
++makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'execute-and-export', 'in-memory-graphql.ts (excerpt)')
 :marked
-  Now all that's left is to connect the new in-memory server into our Apollo Client configuration:
+  Now all that's left is to connect the new in-memory server to the Apollo Client configuration 
+  by importing `networkInterface` and adding it to the `client` constant in `client.ts`.
 +makeExample('heroes-graphql/ts/src/app/client.ts', '', 'client.ts')
 :marked
-  That's it.  now you can run your application as if you had a GraphQL server connected to it but,
-  there is no persistance - everything is running in-memory browser right now, so when you refresh the page, all changes will be lost.
+  That's it.  Now you can run your application as if you had a GraphQL server connected to it. 
+  However, there is no persistance&mdash;everything is running in-memory in the browser, 
+  so when you refresh the page, all changes will be lost.
+
+  Now that you have a local server set up, you have some options:
+  * You can store everything on the browser's local-storage using local-storage database libraries.
+  * You can make the resolver functions call your server's existing REST endpoint.
+  * You can start a separate Node GraphQL server and simply move the code into it for persistance.
+
+.alert.is-important
+  :marked
+    Uri: Let's add a conclusion showing what was accomplished in the doc. 
+    Maybe something like (please add anything I've missed):
+
+.l-main-section
+:marked
+  ## Conclusion
+
+  This cookbook covered:
+
+  - How to create a basic GraphQL query.
+  - How to create a basic GraphQL mutation.
+  - How to build a GraphQL server.
+
 
-  more things you can do now that you have it setup:
-  * You can store everything on the browser's local-storage using local-storage database libraries
-  * You can make the resolver functions call your server's existing REST endpoint
-  * You can start a separate Node GraphQL server and simply move the code in there -
-  now you will have persistance and you became a backend developer ;)
 
 .l-main-section
 <a id="example"></a>