docs(cookbook/graphql): More @kapunahelewong review fixes

Author: Urigo

public/docs/_examples/heroes-graphql/ts/src/app/in-memory-graphql.ts

@@ -16,14 +16,14 @@ type Hero {
   name: String!
 }
 
-# the schema allows the following queries:
+# The schema allows the following queries:
 type Query {
   heroes(search: String): [Hero]
 
   hero(heroId: Int!): Hero
 }
 
-# this schema allows the following mutation:
+# This schema allows the following mutation:
 type Mutation {
   updateHero (
     id: Int!
@@ -39,8 +39,8 @@ type Mutation {
   ): Hero
 }
 
-# you need to tell the server which types represent the root query
-# and root mutation types. you call them RootQuery and RootMutation by convention.
+# Tell the server which types represent the root query and root mutation types.
+# By convention, they are called RootQuery and RootMutation.
 schema {
   query: Query
   mutation: Mutation

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

@@ -218,6 +218,13 @@ a#http-heroes
     This cookbook touches on the main points of using GraphQL with Angular. 
     The full documentation can be found on the [Apollo Client docs website](http://dev.apollodata.com/).
 
+:marked
+  The starting point for the app would be the Tour Of Heroes tutorial app at it's end state.
+  You can download that app [here](https://github.com/johnpapa/angular2-tour-of-heroes/archive/master.zip).
+
+  You will gradually migrate that app from using REST to using GraphQL.
+
+
 .l-main-section
 <a id="installation"></a>
 :marked
@@ -384,57 +391,28 @@ code-example(language="json").
 
   Apollo's `mutate` function returns the result as an Observable.
   The Observable returns a `mutationResult` variable that is structured 
-  like the `ApolloQueryResult` Typescript Type, where the generic `T` type is a `Hero` type:
+  like the `ApolloQueryResult` TypeScript Type, where the generic `T` type is a `Hero` type:
 code-example(language="json").
   type ApolloQueryResult&lt;T> = {
     data: T;
     loading: boolean;
     networkStatus: NetworkStatus;
   };
 :marked
-  and that's also how you reference that result variable in Typescript.
-  So in order the get the actual hero data being returned, you access those values like so:
+  If this looks familiar, it's because that's also how you reference the `mutationResult` variable in TypeScript.
+  To access the hero data `mutationResult` returns, use dot notation to traverse `mutationResult` and assign it to a new hero object.
 +makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'access-mutation-result', 'heroes.component.ts')
 :marked
-  and then push them into the `heroes` array.
-
-
-.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`.
-    :Kapunahele - changed above
+  Once you have created the new object with the data, push it into the `heroes` array.
 
 :marked
   Just like a query, the mutate function returns an Observable you can subscribe to 
   that handles the data you request.
 
-  At this point, your heroes existing heroes app can also add a hero:
+  At this point, your existing heroes app can also add a hero:
 figure.image-display
   img(src='/resources/images/cookbooks/heroes-graphql/heroes- graphql-mutation.gif' alt="Heroes GraphQL Mutation")
 
-
-.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.
-    ::Kapunahele - great point. added.
-
 .l-main-section
 <a id="resources"></a>
 :marked
@@ -467,13 +445,6 @@ figure.image-display
   benefits for not needing to sync multiple REST requests and join logic 
   on the client.
 
-.alert.is-important
-  :marked
-    Uri: Can you tell me why it makes it easier? We should say 
-    "...logic on the client because..."
-    :Kapunahele - changed above
-
-
 .l-sub-section
   :marked
     To read more about how to run a full GraphQL backend, see the [Apollo Server documentation](http://dev.apollodata.com/tools/).
@@ -485,12 +456,6 @@ figure.image-display
     similar to Firebase, but based on the GraphQL API spec.
     For help on getting up and running, see [Scaphold](https://www.scaphold.io/) and [Graphcool](https://www.graph.cool/).
 
-.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.
-    :Kapunahele - the word `but` was wrong. fixed and edited a bit
-
 :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. 
@@ -504,11 +469,12 @@ code-example(language="sh" class="code-shell").
   and paste in the following schema:
 
 +makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'graphql-schema', 'in-memory-graphql.ts')
+:marked
+  The schema starts with a representions of the model of data the server exposes. 
+  Then the schema specifies what queries are allowed on that data, followed by specifing 
+  what mutations (actions) clients are allowed to do on the server.
+  The end of the schema provides the above definitions as the root types the GrpahQL server will expose.
 
-.alert.is-important
-  :marked
-    Uri: Could you change the use of "we" in the above comments to "you" or the imperative (command without 
-    "you")? :Kapunahele - done.
 .l-sub-section
   :marked
     While the schema includes the major points covered in this cookbook, 
@@ -537,31 +503,14 @@ code-example(language="sh" class="code-shell").
     npm install lodash --save  
 +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).
-    :Kapunahele - fixed. for ease of use I've installed all of lodash
-
-
 :marked
   Notice that the server includes functions that correspond to each 
   type in the schema _and_ the mutations.
 
   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 because if you don't need to know the specific
-  query the client makes to create the server Implementation.
-
-.alert.is-important
-  :marked
-    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.
-    :Kapunahele - expanded on that, let me know if that works
+  This removes the coupling between the frontend and backend because you don't need to know the specific
+  query the client makes to create the server implementation.
 
 :marked
   Now, connect the schema to the resolvers with the `makeExecutableSchema` function from
@@ -580,12 +529,7 @@ code-example(language="sh" class="code-shell").
   library and export it so you can use it with the Apollo Client. 
   First, `npm install`:
 code-example(language="sh" class="code-shell").
-    npm install graphql --save    
-
-.alert.is-important
-  :marked
-    Uri: can you provide the npm install command?
-    :Kapunahele - done
+    npm install graphql --save
 
 :marked
   Next, add an import statement for `execute`.
@@ -594,21 +538,15 @@ code-example(language="sh" class="code-shell").
 :marked
   Now create a new `networkInterface` class and call it `InBrowserNetworkInterface`.
 
-  That class will have a `schema` property which it will initialize in the constructor.
+  This class will have a `schema` property which it will initialize in the constructor.
 
-  Then create a `query` function that will recieve a query as a variable and execute that query using
-  `graphql` execute function against the schema property.
+  Next, the `query` function takes as an argument the query request and executes 
+  that query using the GraphQL `execute` function against the schema property.
 
-  You send empty objects to the `rootValue` and `contextValue` arguments of the function and send the 
-  `variables` and `operationName` arguments that are related to the query request.
+  You send empty objects to the `rootValue` and `contextValue` arguments of the function with `{}` and `{}` respectively 
+  and send the `variables` and `operationName` arguments that are related to the query request.
 
-  Now export the new `InBrowserNetworkInterface` class in order to import it to Apollo Client.
-.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.
-    :Kapunahele - let me know if that works
+  Lastly export the new `InBrowserNetworkInterface` class in order to import it to Apollo Client.
 +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 to the Apollo Client configuration 
@@ -624,12 +562,6 @@ code-example(language="sh" class="code-shell").
   * 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):
-    :Kapunahele - done, but not sure if its enough?
-
 .l-main-section
 :marked
   ## Conclusion