docs(cookbook/graphql): edits up through Performing Mutations

Author: kapunahelewong

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

@@ -14,7 +14,7 @@ include ../_util-fns
 
 <a id="toc"></a>
 :marked
-  ## Table of contents
+  ## Contents
 
   - [What is GraphQL?](#what-is-graphql)
 
@@ -106,12 +106,8 @@ a#http-heroes
   1. A dependency between the service and all of the components that use it
   make the component no longer reusable. If you change something in the service,
   it might break other components that use that service.
-  2. There is a main, complex point to handle batching, caching, and join logic.
-
-.alert.is-important
-  :marked
-    Uri: Could you add a sentence to #2 above explaining why this
-    is a bad idea like you did in #1?
+  2. There is a main, complex point to handle batching, caching, and join logic. 
+  Because the logic is shared between components, the potential of things breaking increases.
 
 :marked
   #### Fetching data at the parent component and passing it down the component tree
@@ -133,55 +129,37 @@ a#http-heroes
 
 
 :marked
-  Here, the data dependency is inside or next to the component and when the data dependency changes,
-  the component is the only thing that was changed&mdash;no service or parent component were harmed in the making of this component.
-
-.alert.is-important
-  :marked
-    Uri: The above sentence could use some editing, but as I started, I wasn't sure I was
-    saying the right thing. Does this work?
-
-    "Here, the data dependency is inside the component. Alternatively, it could go next to
-    the component. When the data dependency changes, only the component need change.
-    You don't have to touch any services or parent components."
-
-    What do you mean by "next to it" exactly? Could we say that explicitly? I also like the
-    tone of "were harmed in the making of..." but since I have to change to the present tense
-    the reference isn't as smooth. If you can work it in, I'm fully supportive. I thought
-    it was a good way to make the point.
+  Here, the data dependency is inside the component. The query reflects just 
+  what the single component needs and is included as part of the 
+  component or a wrapper component. That means that when the 
+  data dependency changes, the component is the only thing 
+  impacted. You don't have to touch any services or parent components.
 
 :marked
-  Now, a single component contains all the data dependency changes.
-
-.alert.is-important
-  :marked
-    Uri: Could you explain the `watchQuery` code snippet below? Just a couple of sentences would
-    work.
+  Now, a single component contains all of its own data dependency changes.
 
 :marked
-  (Explanation could go here followed by the fact that it simplifies adding `age`....)
-  For example, adding an `age` field to the app is simple:
+  The `watchQuery` function tells the Apollo Client what data 
+  this component needs. The Apollo Client then returns the 
+  necessary data to the component as an Observable.
+  For example, adding an `age` field to the app is 
+  simple because you only change the component itself:
 
 +makeExample('heroes-graphql/ts/src/app/hero-detail.component.1.ts','graphql-query-new-field','Adding an `age` field to the component')
 +makeExample('heroes-graphql/ts/src/app/hero-detail.component.1.html','template-new-field','Adding an `age` field to the template')
 
-.alert.is-important
-  :marked
-    Uri: This section where you show the solution is where you're selling the idea -
-    where you're showing the reader why they should continue in this doc. Could you
-    make that point here in a sentence or two? I'd try but don't quite understand
-    it yet.
-
+:marked
+  So far, you've seen how to fetch data for a component while 
+  keeping the component isolated from the rest of the app.
+  That solves the most time-consuming and bug provoking code 
+  that one usually writes in order to fetch data from the server.
+  You can also use GraphQL to improve efficiency.
 
 :marked
   ### Network Performance
 
-  The [Heroes HTTP example](#http-heroes) calls `getHeroes` to fetch all heroes and their information.
-
-.alert.is-important
-  :marked
-    Uri: Not sure I linked the above to the right spot. If so, the text in both places should
-    read the same. It's linking to "Using a Service" because that's where I saw `getHeroes`.
+  The [Tour of Heroes HTTP guide](latest/tutorial/toh-pt6.html) 
+  calls `getHeroes` to fetch all heroes and their information.
 
 :marked
   That might work for simple cases but the problem here is that `getHeroes` might fetch
@@ -191,16 +169,27 @@ a#http-heroes
   server, you might break the components that use that endpoint.
 
   The other approach would be to call `getHeroes`, get the ids of the heroes and call `getHero` for each id.
-  That might result in multiple requests to the server for one single render of the page.
+  That might result in _multiple requests to the server_ for one single render of the page.
 
-  With a REST API, you would always have to choose between those two options and the problems of each option.
+  With a REST API, you _always have to choose between those two options_ and 
+  their respective problems.
 
-  With GraphQL, you just specify the dependency of each component and a GraphQL client library, like [Apollo-Client](http://dev.apollodata.com/),
-  to merge those into one single network request. GraphQL sends back the information
+:marked
+  With GraphQL, you just specify the dependency of each component and a 
+  GraphQL client library, like the [Apollo Client](http://dev.apollodata.com/),
+  to merge those into **one single network request**. GraphQL sends back the information
   in a single response, with exactly the information you need&mdash;no more, no
-  less&mdash;and no need to do complex joins or wait for responses.
+  less&mdash;in exactly the structure and shape you want the data to be with 
+  no need to do complex joins or wait for responses.
 
-  ### Typed API and tooling
+.l-sub-section
+  :marked
+    You can work with the Apollo Client 
+    while still keep your existing REST services in your Angular app 
+    and migrate gradually from them.
+
+:marked
+  ### Typed API, tooling and auto documentation
 
   Just as TypeScript provides tooling to increase productivity and best practices,
   GraphQL provides a similar solution for working with APIs.
@@ -209,29 +198,20 @@ a#http-heroes
   can change without notice.
 
   With GraphQL, the schema is typed and shared between the client
-  and the server so you can get the same benefits when working with
-  the network&mdash;validation and autocompletion inside the IDE at development time.
-
-.alert.is-important
-  :marked
-    Uri: I don't understand this last sentence above. I get lost at "working with the
-    network...". What do you mean exactly? I realize it might just be beyond my experience,
-    but could you explain it to a mid-level dev?
-
+  and the server. As a result, just as with Angular and TypeScript, 
+  you get the same development experience when calling calling a remote 
+  API&mdash;validation and autocompletion inside the IDE at development time.
 
 .l-main-section
 <a id="how-to"></a>
 :marked
   ## How to use GraphQL in an Angular app
 
   This guide uses [Apollo-Client](http://dev.apollodata.com/) as the GraphQL client for Angular.
-  Apollo helps you query GraphQL and provides X, Y, and Z.
-
-.alert.is-important
-  :marked
-    Uri: Could you specify those benefits where I wrote "X, Y, and Z"? I would but am still 
-    trying to wrap my mind around it. I think this is talking about what you 
-    touched on in the solution section, but I wasn't clear on all the benefits there.
+  Apollo helps you query GraphQL and provides a caching layer 
+  with common features you need for querying a server such as 
+  caching, mutations, optimistic UI, real-time subscriptions, 
+  pagination, server-side rendering, and prefetching.
 
 .l-sub-section
   :marked
@@ -251,37 +231,22 @@ code-example(language="sh" class="code-shell").
   Next, initialize the client by creating a new file called `client.ts` and 
   pasting in the following code:
 
-.alert.is-important
-  :marked
-    Uri: Now that we are telling people to copy the code into their project, we should 
-    use the blue headers on the code snippets to name the file and show where it is, 
-    such as `app/client.ts`, like this:
-
 +makeExample('heroes-graphql/ts/src/app/client.1.ts', '', 'app/client.ts')
 :marked
-  This is the default initialization of Apollo and is referred to as the `/graphql` endpoint. 
+  This is the default initialization of Apollo and calls the `/graphql` endpoint. 
   First, import `ApolloClient`, create a constant for the new instance of the client, 
   and export it so that it is available to the app.
 
-
-.alert.is-important
+.l-sub-section
   :marked
-    Uri: I'm a little confused here. Is this (below) a necessary step? Can we start by showing them 
-    the above code and then telling them to paste in this snippet so they don't have to 
-    immediately paste over something that they just put in their project? 
-    Do we need to change the endpoint? If both snippets are needed, 
-    let's explain why. Both are fine to have if we can lead the reader through why. 
-
-    If this is more of a handy piece of info to simply have in one's repertoire, we could 
-    put this in an aside or a note, so people don't think it's a step they 
-    have to follow for this guide.
-
-:marked
-  To change the [settings](http://dev.apollodata.com/core/apollo-client-api.html#ApolloClient\.constructor) 
-  of `ApolloClient`, call its constructor with different parameters. 
-  For example, you can alter the endpoint by importing `createNetworkInterface` and configuring the 
-  `networkInterface` property of `ApolloClient` to 
-  use a URI:
+    ### To use a different URI for the Apollo Client
+    You don't need the following code snippet to work through this cookbook, 
+    but it's good to know how to configure the client to use a URI. 
+    To change the [settings](http://dev.apollodata.com/core/apollo-client-api.html#ApolloClient\.constructor) 
+    of `ApolloClient`, call its constructor with different parameters. 
+    You can alter the endpoint by importing `createNetworkInterface` and configuring the 
+    `networkInterface` property of `ApolloClient` to 
+    use a URI:
 
 +makeExample('heroes-graphql/ts/src/app/client.2.ts', 'network-initialization', 'app/client.ts')
 .l-sub-section
@@ -291,96 +256,55 @@ code-example(language="sh" class="code-shell").
     The appendix shows you how to run a GraphQL server in-memory 
     on the client, which is helpful for testing.
 
-.alert.is-important
-  :marked
-    Uri: Two things. 
-    
-    1. For the above, you had that it was a good way to move your app 
-    gradually to GraphQL. Could you explain why? We can put that in there, 
-    I just couldn't figure out how to work that phrase into a sentence.
-
-    2. If the project in this guide requires the server, we should consider 
-    moving it up, taking it out of an appendix. What do you think?
-
 :marked
   After initializing the Apollo client, import the `ApolloModule` 
   into the app's root module:
 +makeExample('heroes-graphql/ts/src/app/app.module.ts', 'import-apollo', 'app.module.ts (excerpt)')
 
 :marked
-  Next, add `ApolloModule.withClient(getClient)` to the `@NgModule` imports array.
+  Next, add `ApolloModule.forRoot(getClient)` to the `@NgModule` imports array. This 
+  is an initialization function that accepts the Apollo configuration 
+  you created earlier as an argument and creates a new Apollo instance for the app.
 
-.alert.is-important
-  :marked
-    Uri: Could you explain `ApolloModule.withClient(getClient)`?
 +makeExample('heroes-graphql/ts/src/app/app.module.ts', 'apollo-ngmodule', 'app.module.ts (excerpt)')
 
 .l-main-section
 <a id="querying"></a>
 :marked
   ## Performing a query
 
-  With GraphQL you always query a server that has a schema representing the data it exposes. 
-  A schema is or serves as a ...
-
-  The server for this guide is based on the [Tour of Heroes](link here please). 
+  With GraphQL you query a schema, which is organized into types and fields,
+  that represents the data you can query. 
+  
+  The server for this guide is based on the [Tour of Heroes](ts/latest/tutorial/). 
   Copy the schema that follows into a file named `in-memory-graphql.ts` in the `app` directory:
 
-.alert.is-important
-  :marked
-    Uri: 
-    
-    1. Could you define schema right after you first mention it? I've started the 
-    sentence for you above so you can see what I have in mind. Feel free to 
-    change/move it though.
-
-    2. Could you link the above "Tour of Heroes" to the place you're referencing?
-
-    3. Could you add a sentence or two here explaining what's happening in the schema? 
-    The comments are good, but we also want to have a continuous thread in the prose 
-    voice that carries us through. 
-
-    4. In explaining the schema, just a sentence or two about what the different parts 
-    are would be helpful with a little about the syntax. For example, I think I 
-    can declare certain types - what are they and what's that curious syntax? We want 
-    to tell them declaratively, rather than leaving them to their own assumptions. 
-    
-    4. Please be sure to remove "we", "let's", "our/s" and "us" 
-    from comments as well as the jade. I've been removing them here, but it's 
-    possible that I have missed some. I haven't gone into the `_example` files.
+:marked
+  The schema begins with data types and fields followed by the specific queries 
+  you can perform on the data. These are in turn followed by 
+  mutations, which are _actions_ that you 
+  can call on the server, similar to a POST request in REST.
 
 +makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'graphql-schema', 'app/in-memory-graphql.ts')
 
 :marked
-  To use the schema, start by importing `Apollo` into `heroes.component.ts`, 
+  To start querying data, begin by importing `Apollo` into `heroes.component.ts`,
   and injecting it into the constructor:
 +makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'import-apollo', 'heroes.component.ts (excerpt)')
 +makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'inject-apollo', 'heroes.component.ts (excerpt)')
 :marked
   Now that the schema is available to the app, the next step is querying it. 
   In the component, import `gql` from the `graphql-tag` library. 
-  The `gql` function parses regular string literals as GraphQL.
-
-.alert.is-important
-  :marked
-    Uri: Could you explain in just a sentence or two what it means when 
-    we parse string literals as GraphQL? 
+  The `gql` function turns your query string to something `Apollo` 
+  can accept and understand.
 
 +makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'import-graphql-tag', 'heroes.component.ts')
 
 :marked
-  To query data with the Apollo Client, pass `Apollo` a query in the GraphQL 
-  query syntax. In this example, ...... 
-.alert.is-important
-  :marked
-    Uri: Could you give a brief explanation of what's happening in the below 
-    code snippet? Please touch on if we are putting it in the component (I think so),
-    and what each section means. This is a really important part of this tutorial and 
-    people will be very interested in the unique syntax. Brief is fine, since we don't 
-    want to go too far into it, but we should exaplain on this page what each line means. 
-    This might be 2 or 3 short paragraphs. Please also touch on the use of observables. 
-    You can say something to the effect that we are using observables here because x and 
-    they can tell that because of `subscribe`. You could include a link to ....(I'm finding the right link...). 
+  To query data with the Apollo Client, pass a GraphQL query with the 
+  data and structure that you want to the `Apollo` `watchQuery` function. 
+  The `Apollo` ` watchQuery` function will return the data from the 
+  server in the form of an Observable.
 
 +makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'query-heroes', 'heroes.component.ts')
 
@@ -391,15 +315,9 @@ code-example(language="sh" class="code-shell").
   Next, update the template so it will display the results of the query.
 +makeExample('heroes-graphql/ts/src/app/heroes.component.1.html', 'render-heroes', 'heroes.component.html')
 
-.alert.is-important
-  :marked
-    Uri: 
-
-    1. Since we haven't talked about the template yet, do you think we should show 
-    the whole thing with some comments making this section (above) stand out?
-
-    2. Do the results show up at this point? If so, maybe we should mention that. If not, 
-    we should say so.
+:marked
+  At this point, if you have a running [GraphQL server](#server), the browser displays the 
+  fetched data.
 
 .l-main-section
 <a id="mutation"></a>