Edits based on feedback

Author: leebyron

notes/NewSiteArchitecture.md

@@ -10,31 +10,36 @@ This page is effectively a marketing page for GraphQL and should be the visual,
 
 Above the fold, this page should succinctly explain what GraphQL is and illustrate with a simple (editable) query/response example. Before scrolling you should understand the following:
 
-* GraphQL is an query language for APIs.
+* GraphQL solves the same problem as REST.
+* GraphQL is an query language for APIs (and not Databases).
 * GraphQL is sent by client applications, such as an iOS app.
 * GraphQL is evaluated by a web service and often returned as JSON.
-* GraphQL typically replaces REST.
+* GraphQL services provide a complete description of your data with a type system.
+* It's easy to build powerful tools for your data using GraphQL.
 
 Below the fold we should introduce concepts one at a time, each with visual metaphor and take-aways:
 
-1) GraphQL describes what a client needs in terms of how client developers think about data.
+1) GraphQL clients describe what they need in terms of how client developers think about data.
 
 * If you're familiar with JSON, GraphQL is easy to learn and understand.
-* It's easy to anticipate the shape of the result for any query.
-* GraphQL only sends what you ask for, nothing more or less.
+* GraphQL only sends what you ask for, nothing more or less, making your app faster and more stable.
+* It's easy to anticipate the shape of the result of any query.
 
 2) GraphQL queries can access many "resources" in a single network request.
 
 * A query can access properties of not just one object, but of many related objects.
-* Compared to REST, GraphQL requires much less network activity.
+* A query can access multiple unrelated objects at once.
+* Compared to REST, GraphQL collects all the data needed for your app with much less network activity, making your app faster.
 
-3) GraphQL services provide a type system.
+3) GraphQL services describes what's possible with a strong type system.
 
+* GraphQL services provide a complete description of your data.
 * Every `{ }` corresponds to an object of a particular type, and every type describes the fields available.
-* GraphQL only runs queries that make sense.
+* GraphQL only runs queries that make sense and provides helpful error messages.
 * Tools and IDEs can make editing queries easy via type-aheads.
   * GraphiQL is a free tool that you can use.
 * Type system defines descriptions, making it easy to keep documentation up to date.
+* Every query guarantees the shape and type of its response.
 
 4) GraphQL is composable via fragments.
 
@@ -47,14 +52,14 @@ Below the fold we should introduce concepts one at a time, each with visual meta
 * Server does not need to worry about concerns of any particular client, only the complete set of capabilities. Clients are responsible for the data they receive.
 * Because GraphQL only sends what you ask for, new capabilities can be introduced via new fields on types with no impact on existing queries.
 * Old capabilities can be marked "deprecated" with no impact on existing queries.
-* Far fewer reasons for versioning your API when using GraphQL.
+* No versioning your API when using GraphQL leads to cleaner code on the server.
 
 6) GraphQL queries are answered by simple functions on your server.
 
 * GraphQL is not backed by any database technology, just like REST.
 * Every field on each type is represented by a function for retrieving that data.
-* A GraphQL executor will call your functions and use as much concurrency as possible.
-* Possibilities are endless for connecting to your server's existing data model.
+* GraphQL will call your functions and execute a query with optimal concurrency.
+* It's easy to write a GraphQL API using your existing data model.
 
 Finally, there will be a set of links for learning more (diving into `Learn`) and for getting started (in `Code`). As well as a wall-o-logo for companies using GraphQL.
 
@@ -76,45 +81,46 @@ The landing page for this section should begin as a more information-rich introd
 
 There is then a TOC through the sections and chapters (this is a straw-man list, open to reordering and addition)
 
+* Introducing GraphQL (this initial page)
 * Core Concepts:
-  * Query Language:
-    * Basics (queries, fields, arguments, aliases, comments)
+  * Requests:
+    * Basics (queries & mutations, fields, arguments, aliases, comments)
     * Variables
     * Fragments
     * Values
     * Directives (skip & include)
   * Type System:
     * Basics (Schema, Objects & Fields)
-    * Scalars
-    * Lists & NonNull
-    * Interfaces
-    * Unions
-    * Enums
-  * Advanced Topics:
+    * Scalars & Enums
+    * Lists & NonNull (mention error handling)
+    * Interfaces & Unions
+  * How GraphQL Works:
     * Validation
     * Execution & Error Handling
     * Introspection
-    * Mutations
 * Best Practices:
   * Servers:
-    * Schema Design Guidelines
-    * Paginating Lists
-    * Non-Breaking Changes
-    * Performant Servers (Batching & Caching)
-    * Authentication & Authorization
     * Serving over HTTP
+    * Authentication & Authorization
+    * Mutations
+    * Paginating Lists
+    * Schema Changes & Versioning
+    * Query Performance (Batching & Caching)
+    * Security & Rate Limiting
+    * Schema Design Guidelines
   * Clients:
     * Using Variables
     * Co-locating Fragments
     * Caching Results
     * Persisted Queries
     * Generating Models
+    * Migrating from REST
 
 ## Code
 
 *Goal:* Introduce open source GraphQL tools along with quick getting started guidelines for each.
 
-*Timeframe:* Top 3 servers described by Sept 12th, remainder by Sept 30th.
+*Timeframe:* At least 3 servers described by Sept 12th, remainder by Sept 30th.
 
 This page is all about fulfilling the "Ok I'm sold! Now what?" conundrum. It should first very quickly reintroduce the elements of GraphQL you would expect to see software for as well as offer a quick path towards getting something working.
 
@@ -141,7 +147,7 @@ Hosted GraphQL-as-a-service have an opportunity to pitch themselves here.
 
 4) Tools
 
-Highlight many common tools and libraries used by GraphQL community, e.g. GraphiQL.
+Common tools used by GraphQL community, e.g. GraphiQL.
 
 ## Community