From 43725c45eff1ea78323b3b0e71962e6f67a444d6 Mon Sep 17 00:00:00 2001
From: carolstran <carolynstransky@gmail.com>
Date: Thu, 19 Nov 2020 13:59:00 +0100
Subject: [PATCH 01/11] Initial design - not pretty

---
 src/components/FAQLayout/index.tsx | 71 ++++++++++++++++++++---
 src/content/faq/General.md         | 90 ++++++++++++++++++++++++++----
 src/templates/doc.tsx              | 14 ++++-
 3 files changed, 154 insertions(+), 21 deletions(-)

diff --git a/src/components/FAQLayout/index.tsx b/src/components/FAQLayout/index.tsx
index e84d0b2af4..ce8a21f959 100644
--- a/src/components/FAQLayout/index.tsx
+++ b/src/components/FAQLayout/index.tsx
@@ -5,23 +5,80 @@ import { toSlug } from '../../utils/slug'
 
 interface Props {
   title: string
-  questions: string
+  gettingStartedQuestions: string
+  generalQuestions: string
+  bestPracticesQuestions: string
+  specificationQuestions: string
+  frontendQuestions: string
   rawMarkdownBody: string
 }
 
-const index = ({ title, questions, rawMarkdownBody }: Props) => {
+const index = ({ title, gettingStartedQuestions, generalQuestions, bestPracticesQuestions, specificationQuestions, frontendQuestions, rawMarkdownBody }: Props) => {
   return (
     <section>
       <div className="documentationContent">
         <div className="inner-content">
           <h1>{title}</h1>
-          {questions && (
+          {gettingStartedQuestions && (
               <div>
-                  {questions
+                  <h2>Getting Started</h2>
+                  {gettingStartedQuestions
                     .split(',')
-                    .map(question => (
-                        <Link className="faq-questions" key={question} to={`#${toSlug( question )}`}>
-                            {question}
+                    .map(gettingStartedQuestion => (
+                        <Link className="faq-questions" key={gettingStartedQuestion} to={`#${toSlug( gettingStartedQuestion )}`}>
+                            {gettingStartedQuestion}
+                        </Link>
+                    ))
+                  }
+              </div>
+          )}
+          {generalQuestions && (
+              <div>
+                  <h2>General</h2>
+                  {generalQuestions
+                    .split(',')
+                    .map(generalQuestion => (
+                        <Link className="faq-questions" key={generalQuestion} to={`#${toSlug( generalQuestion )}`}>
+                            {generalQuestion}
+                        </Link>
+                    ))
+                  }
+              </div>
+          )}
+          {bestPracticesQuestions && (
+              <div>
+                  <h2>Best Practices</h2>
+                  {bestPracticesQuestions
+                    .split(',')
+                    .map(bestPracticesQuestion => (
+                        <Link className="faq-questions" key={bestPracticesQuestion} to={`#${toSlug( bestPracticesQuestion )}`}>
+                            {bestPracticesQuestion}
+                        </Link>
+                    ))
+                  }
+              </div>
+          )}
+          {specificationQuestions && (
+              <div>
+                  <h2>Specification</h2>
+                  {specificationQuestions
+                    .split(',')
+                    .map(specificationQuestion => (
+                        <Link className="faq-questions" key={specificationQuestion} to={`#${toSlug( specificationQuestion )}`}>
+                            {specificationQuestion}
+                        </Link>
+                    ))
+                  }
+              </div>
+          )}
+          {frontendQuestions && (
+              <div>
+                  <h2>Frontend</h2>
+                  {frontendQuestions
+                    .split(',')
+                    .map(frontendQuestion => (
+                        <Link className="faq-questions" key={frontendQuestion} to={`#${toSlug( frontendQuestion )}`}>
+                            {frontendQuestion}
                         </Link>
                     ))
                   }
diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index 35cee2fffd..027282e79a 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -3,7 +3,11 @@ title: Frequently Asked Questions (FAQ)
 layout: faq
 category: General
 permalink: /faq/
-questions: Why should I use GraphQL?,Is GraphQL a database language like SQL?,Does GraphQL replace REST?,How can I learn GraphQL?,Is GraphQL frontend or backend?,Is GraphQL only for React or JavaScript developers?,What is a GraphQL client and why would I use one?,Is GraphQL owned by Facebook?,What is the GraphQL Foundation?,How can I contribute to the GraphQL specification?
+gettingStartedQuestions: Why should I use GraphQL?,Does GraphQL replace REST?,How can I learn GraphQL?,Is GraphQL a database language like SQL?,Is GraphQL only for React or JavaScript developers?
+generalQuestions: Is GraphQL frontend or backend?,Does GraphQL use HTTP?,What is a GraphQL client and why would I use one?,Does GraphQL replace ORMs?,Is GraphQL owned by Facebook?,Who is behind GraphQL?,What is the GraphQL Foundation?
+bestPracticesQuestions: How does GraphQL affect my product’s performance?,Does GraphQL support offline usage?,What are the security concerns with GraphQL?,How can I set up authorization with GraphQL?,How does authentication work with GraphQL?,Is GraphQL the right fit for designing a microservice architecture?,How can I document my GraphQL API?
+specificationQuestions: What’s the best way to follow specification releases?,How can I contribute to the GraphQL specification?
+frontendQuestions: Does GraphQL replace Redux or other state management libraries?
 ---
 
 ## Why should I use GraphQL?
@@ -20,14 +24,6 @@ It depends on your use case, but in general, GraphQL has a few key features that
 
 You can try out GraphQL without rewriting your entire application. For example, starting with a single HTTP request that wraps an existing REST call. Your [GraphQL schema](/learn/thinking-in-graphs/#shared-language) and [business domain model](/learn/thinking-in-graphs/#business-logic-layer) can expand gradually. We recommend focusing on one use case at first and only building the part of the schema needed for that. 
 
-## Is GraphQL a database language like SQL?
-
-No, but this is a common misconception.
-
-GraphQL is a specification typically used for remote client-server communications. Unlike SQL, GraphQL is agnostic to the data source(s) used to retrieve data and persist changes. Accessing and manipulating data is performed with arbitrary functions called [resolvers](/learn/execution/). GraphQL coordinates and aggregates the data from these resolver functions, then returns the result to the client. Generally, these resolver functions should delegate to a [business logic layer](/learn/thinking-in-graphs/#business-logic-layer) responsible for communicating with the various underlying data sources. These data sources could be remote APIs, databases, [local cache](/learn/caching/), and nearly anything else your programming language can access.
-
-For more information on how to get GraphQL to interact with your database, check out our [documentation on resolvers](/learn/execution/#root-fields-resolvers).
-
 ## Does GraphQL replace REST?
 
 No, not necessarily. They both handle APIs and can [serve similar purposes](/learn/thinking-in-graphs/#business-logic-layer) from a business perspective. GraphQL is often considered an alternative to REST, but it’s not a definitive replacement.
@@ -44,9 +40,13 @@ For more practical guides, visit the [How to GraphQL](https://www.howtographql.c
 
 Before you start your learning journey, make sure you know what an API is and how communication generally works between client and server.
 
-## Is GraphQL frontend or backend?
+## Is GraphQL a database language like SQL?
 
-Both. GraphQL specifies how you can [exchange information between client and server](https://www.howtographql.com/basics/3-big-picture/). This includes how the server can indicate [what data and operations are available](/learn/introspection/), how the client should [format requests](/learn/queries/), how the server should [execute these queries](/learn/execution/), and what the client will [receive in response](/learn/serving-over-http/#response).
+No, but this is a common misconception.
+
+GraphQL is a specification typically used for remote client-server communications. Unlike SQL, GraphQL is agnostic to the data source(s) used to retrieve data and persist changes. Accessing and manipulating data is performed with arbitrary functions called [resolvers](/learn/execution/). GraphQL coordinates and aggregates the data from these resolver functions, then returns the result to the client. Generally, these resolver functions should delegate to a [business logic layer](/learn/thinking-in-graphs/#business-logic-layer) responsible for communicating with the various underlying data sources. These data sources could be remote APIs, databases, [local cache](/learn/caching/), and nearly anything else your programming language can access.
+
+For more information on how to get GraphQL to interact with your database, check out our [documentation on resolvers](/learn/execution/#root-fields-resolvers).
 
 ## Is GraphQL only for React or JavaScript developers?
 
@@ -54,6 +54,14 @@ No, not at all. [GraphQL is a specification](https://spec.graphql.org/) that can
 
 It’s understandable why you’d think this, though. GraphQL was introduced at a [React conference](https://www.youtube.com/watch?v=9sc8Pyc51uU) and [GraphQL.js](/graphql-js/) is one of the most widely used implementations to date. We know this can be confusing, so we’re working to improve our documentation and add more code samples that aren’t written in JavaScript.
 
+## Is GraphQL frontend or backend?
+
+Both. GraphQL specifies how you can [exchange information between client and server](https://www.howtographql.com/basics/3-big-picture/). This includes how the server can indicate [what data and operations are available](/learn/introspection/), how the client should [format requests](/learn/queries/), how the server should [execute these queries](/learn/execution/), and what the client will [receive in response](/learn/serving-over-http/#response).
+
+## Does GraphQL use HTTP?
+
+<!-- TODO -->
+
 ## What is a GraphQL client and why would I use one?
 
 GraphQL clients can help you handle [queries, mutations,](/learn/queries/) and [subscriptions](https://spec.graphql.org/draft/#sec-Subscription) to a [GraphQL server](https://www.howtographql.com/advanced/1-server/). They use the underlying structure of a GraphQL API to automate certain processes. This includes batching, UI updates, build-time schema validation, and more.
@@ -62,20 +70,80 @@ A [list of GraphQL clients](/code/#graphql-clients) in various languages is avai
 
 You don't need a specific client to work with GraphQL, though. You might want to start out by [issuing GraphQL results with a regular HTTP client](/learn/serving-over-http/). Then later switch to a GraphQL-optimized client as your application grows in complexity.
 
+## Does GraphQL replace ORMs?
+
+No, GraphQL is a specification. It [doesn’t understand the concept of databases](#is-graphql-a-database-language-like-sql). There are, however, ORMs built specifically for GraphQL. A few of those are listed under the [Services section of our Code page](/code/#services). 
+
 ## Is GraphQL owned by Facebook?
 
 No, GraphQL is governed by the [GraphQL Foundation](#what-is-the-graphql-foundation).
 
 That said, the specification was originally developed at Facebook and [Facebook is a member](https://foundation.graphql.org/members/) of the GraphQL Foundation. You might notice that some of our [GitHub repositories](https://github.com/graphql/) still have the license listed under Facebook Inc. We're updating those and have already converted major projects, like [GraphiQL](https://github.com/graphql/graphiql/blob/main/LICENSE) and [DataLoader](https://github.com/graphql/dataloader/blob/master/LICENSE), to the the new copyright: "Copyright (c) 2020 GraphQL Contributors."
 
+## Who is behind GraphQL?
+
+Loads of people! The [GraphQL specification and all related projects](http://github.com/graphql/) are open source, so anyone is welcome to [contribute](#how-can-i-contribute-to-the-specification). That being said, there is a structure in place behind the repositories - particularly for resolving conflicts within the community and guiding technical decisions. 
+
+The [GraphQL Foundation](#what-is-the-graphql-foundation) provides most of the oversight for GraphQL and is made up of [representatives from 20 different companies](https://foundation.graphql.org/members/). There are also monthly virtual [GraphQL Working Group (WG)](https://github.com/graphql/graphql-wg) meetings. These meetings are operated by the GraphQL Foundation and designed to bring together maintainers of commonly used GraphQL libraries and tools, as well as significant contributors to the GraphQL community. While it tends to be mostly foundation members in attendance, the WG meetings are completely open. Anyone is able to join and [propose items to the agenda](https://github.com/graphql/graphql-wg/blob/master/agendas/). Additionally, GraphQL will soon have a Technical Steering Committee (TSC) to advise on implementation details. More on that coming soon.
+
+If this is confusing, don’t worry - there’s a lot going on. To get a more visual high-level overview, check out the [GraphQL Landscape](https://landscape.graphql.org/).
+
 ## What is the GraphQL Foundation?
 
 The [GraphQL Foundation](https://foundation.graphql.org/faq/) is a neutral foundation that provides governance for GraphQL. This includes vendor-neutral oversight of open-source repositories, funding, events, and more. It's hosted under the [Linux Foundation](https://www.linuxfoundation.org/) and consists of [representatives from dozens of different companies](https://foundation.graphql.org/members/). The idea is that it’s an impartial and open home for the GraphQL community.
 
 You can find out more by visiting [foundation.graphql.org](https://foundation.graphql.org/).
 
+## How does GraphQL affect my product’s performance?
+
+<!-- TODO -->
+
+## Does GraphQL support offline usage?
+
+No, or at least not natively. But there are [GraphQL clients](#what-is-a-graphql-client-and-why-would-i-need-one) that enable you to build offline-first through caching, holding your mutations in a queue, service workers, or another feature designed to perform data operations while offline. 
+
+You can find a [list of GraphQL clients on our Code page](/code/#graphql-clients).
+
+## What are the security concerns with GraphQL?
+
+<!-- TODO -->
+
+## How can I set up authorization with GraphQL?
+
+As tempting as it is to define your authorization logic in your GraphQL implementation, we recommend enforcing authorization behavior in the [business logic layer](/learn/thinking-in-graphs/#business-logic-layer). That way, you have a single source of truth for authorization. 
+
+For a more detailed explanation, go to our [Authorization documentation](/learn/authorization/).
+
+## How does authentication work with GraphQL?
+
+There’s nothing special about it within the specification, but you can implement authentication with common patterns, such as [OAuth](https://oauth.net/) or [JWT](https://jwt.io/). Some [GraphQL libraries](/code/) include a specific protocol for authentication as well. Although if you’re working with a pipeline model, we recommend that [GraphQL should be placed after all authentication middleware](/learn/serving-over-http/#web-request-pipeline).
+
+If you’re using [GraphQL.js](/graphql-js/) to build your API server, we have documentation on [handling authentication with Express middleware](/graphql-js/authentication-and-express-middleware/).
+
+## Is GraphQL the right fit for designing a microservice architecture?
+
+Yes, it can be. If you’re integrating GraphQL into your microservice architecture, we’d recommend having one GraphQL schema as an API gateway rather than having your client talk to multiple GraphQL services. This way, you can split your backend into microservices, but then still aggregate all of your data to the frontend from a single API.
+
+There are many ways to create an API gateway, but the benefit of using GraphQL is that you can take advantage of features like [caching](/learn/caching/), request budgeting, and planning out query schedules.
+
+## How can I document my GraphQL API?
+
+One of the benefits of GraphQL is that it is inherently self-documenting. This means that when you use an interactive tool like [GraphiQL](https://github.com/graphql/graphiql), you’re able to explore what data is exposed by your GraphQL API. This includes the [fields](/learn/queries/#fields), [types](/learn/schema/#type-system), and more. You can also add a [`description` field](https://spec.graphql.org/draft/#sec-Documentation) to provide supplementary notes about your endpoint. 
+
+For many, this provides sufficient API reference documentation. But it doesn’t reduce the need for other forms of documentation, such as guides that explain how the general concepts tie into your specific use case.
+
+## What’s the best way to follow specification releases?
+
+The latest working draft release of the GraphQL specification can be found at [spec.graphql.org/draft](https://spec.graphql.org/draft/). Previous editions can also be found at permalinks that match their [release tag](https://github.com/graphql/graphql-spec/releases).
+
 ## How can I contribute to the GraphQL specification?
 
 GraphQL is still an evolving language and contributions are very welcome! The specification (including the [latest working draft](https://spec.graphql.org/)) is open source. [Contributor guidelines](https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md) are available on GitHub.
 
 There are more ways to get involved with GraphQL beyond the specification though. Updating the content on [this website and the documentation](https://github.com/graphql/graphql.github.io), for example. Or contributing to [graphql-js](https://github.com/graphql/graphql-js), [express-graphql](https://github.com/graphql/express-graphql), [GraphiQL](https://github.com/graphql/graphiql), or [one of the many other projects](https://github.com/graphql/) maintained by the [GraphQL Foundation](#what-is-the-graphql-foundation). 
+
+## Does GraphQL replace Redux or other state management libraries?
+
+No, GraphQL isn’t a state management library - but it can reduce the need for one.
+
+One benefit of state management libraries like Redux is that they can manipulate API responses into a format that your application understands. With GraphQL, you have control over [what data you request](/learn/queries/#fields) and typically results are formatted in a client-friendly way by virtue of the graph design. So this benefit is already built-in. Many [client libraries](https://graphql.org/code/#graphql-clients) can also be used to manage state and have features like caching built-in. You may still decide to implement a state management library, but using it to format response data is generally not necessary.
diff --git a/src/templates/doc.tsx b/src/templates/doc.tsx
index d179668dfa..054278a9a3 100644
--- a/src/templates/doc.tsx
+++ b/src/templates/doc.tsx
@@ -21,7 +21,7 @@ const layoutMap: any = {
 const Blog = ({ data, pageContext }: Props) => {
   const {
     doc: {
-      frontmatter: { title, date, permalink, byline, guestBio, layout, questions },
+      frontmatter: { title, date, permalink, byline, guestBio, layout, gettingStartedQuestions, generalQuestions, bestPracticesQuestions, specificationQuestions, frontendQuestions },
       rawMarkdownBody,
     },
     nextDoc,
@@ -35,7 +35,11 @@ const Blog = ({ data, pageContext }: Props) => {
         permalink={permalink}
         byline={byline}
         guestBio={guestBio}
-        questions={questions}
+        gettingStartedQuestions={gettingStartedQuestions}
+        generalQuestions={generalQuestions}
+        bestPracticesQuestions={bestPracticesQuestions}
+        specificationQuestions={specificationQuestions}
+        frontendQuestions={frontendQuestions}
         rawMarkdownBody={rawMarkdownBody}
         nextDoc={nextDoc}
         sideBarData={pageContext.sideBarData}
@@ -56,7 +60,11 @@ export const query = graphql`
         guestBio
         sublinks
         layout
-        questions
+        gettingStartedQuestions
+        generalQuestions
+        bestPracticesQuestions
+        specificationQuestions
+        frontendQuestions
       }
       id
       rawMarkdownBody

From 133792096a2591b406428079d77747122b3378dd Mon Sep 17 00:00:00 2001
From: carolstran <carolynstransky@gmail.com>
Date: Thu, 19 Nov 2020 13:59:00 +0100
Subject: [PATCH 02/11] Initial design - not pretty

---
 src/components/FAQLayout/index.tsx | 71 ++++++++++++++++++++---
 src/content/faq/General.md         | 90 ++++++++++++++++++++++++++----
 src/templates/doc.tsx              | 14 ++++-
 3 files changed, 154 insertions(+), 21 deletions(-)

diff --git a/src/components/FAQLayout/index.tsx b/src/components/FAQLayout/index.tsx
index e84d0b2af4..ce8a21f959 100644
--- a/src/components/FAQLayout/index.tsx
+++ b/src/components/FAQLayout/index.tsx
@@ -5,23 +5,80 @@ import { toSlug } from '../../utils/slug'
 
 interface Props {
   title: string
-  questions: string
+  gettingStartedQuestions: string
+  generalQuestions: string
+  bestPracticesQuestions: string
+  specificationQuestions: string
+  frontendQuestions: string
   rawMarkdownBody: string
 }
 
-const index = ({ title, questions, rawMarkdownBody }: Props) => {
+const index = ({ title, gettingStartedQuestions, generalQuestions, bestPracticesQuestions, specificationQuestions, frontendQuestions, rawMarkdownBody }: Props) => {
   return (
     <section>
       <div className="documentationContent">
         <div className="inner-content">
           <h1>{title}</h1>
-          {questions && (
+          {gettingStartedQuestions && (
               <div>
-                  {questions
+                  <h2>Getting Started</h2>
+                  {gettingStartedQuestions
                     .split(',')
-                    .map(question => (
-                        <Link className="faq-questions" key={question} to={`#${toSlug( question )}`}>
-                            {question}
+                    .map(gettingStartedQuestion => (
+                        <Link className="faq-questions" key={gettingStartedQuestion} to={`#${toSlug( gettingStartedQuestion )}`}>
+                            {gettingStartedQuestion}
+                        </Link>
+                    ))
+                  }
+              </div>
+          )}
+          {generalQuestions && (
+              <div>
+                  <h2>General</h2>
+                  {generalQuestions
+                    .split(',')
+                    .map(generalQuestion => (
+                        <Link className="faq-questions" key={generalQuestion} to={`#${toSlug( generalQuestion )}`}>
+                            {generalQuestion}
+                        </Link>
+                    ))
+                  }
+              </div>
+          )}
+          {bestPracticesQuestions && (
+              <div>
+                  <h2>Best Practices</h2>
+                  {bestPracticesQuestions
+                    .split(',')
+                    .map(bestPracticesQuestion => (
+                        <Link className="faq-questions" key={bestPracticesQuestion} to={`#${toSlug( bestPracticesQuestion )}`}>
+                            {bestPracticesQuestion}
+                        </Link>
+                    ))
+                  }
+              </div>
+          )}
+          {specificationQuestions && (
+              <div>
+                  <h2>Specification</h2>
+                  {specificationQuestions
+                    .split(',')
+                    .map(specificationQuestion => (
+                        <Link className="faq-questions" key={specificationQuestion} to={`#${toSlug( specificationQuestion )}`}>
+                            {specificationQuestion}
+                        </Link>
+                    ))
+                  }
+              </div>
+          )}
+          {frontendQuestions && (
+              <div>
+                  <h2>Frontend</h2>
+                  {frontendQuestions
+                    .split(',')
+                    .map(frontendQuestion => (
+                        <Link className="faq-questions" key={frontendQuestion} to={`#${toSlug( frontendQuestion )}`}>
+                            {frontendQuestion}
                         </Link>
                     ))
                   }
diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index 515a44f6ba..84a6aa6a44 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -3,7 +3,11 @@ title: Frequently Asked Questions (FAQ)
 layout: faq
 category: General
 permalink: /faq/
-questions: Why should I use GraphQL?,Is GraphQL a database language like SQL?,Does GraphQL replace REST?,How can I learn GraphQL?,Is GraphQL frontend or backend?,Is GraphQL only for React or JavaScript developers?,What is a GraphQL client and why would I use one?,Is GraphQL owned by Facebook?,What is the GraphQL Foundation?,How can I contribute to the GraphQL specification?
+gettingStartedQuestions: Why should I use GraphQL?,Does GraphQL replace REST?,How can I learn GraphQL?,Is GraphQL a database language like SQL?,Is GraphQL only for React or JavaScript developers?
+generalQuestions: Is GraphQL frontend or backend?,Does GraphQL use HTTP?,What is a GraphQL client and why would I use one?,Does GraphQL replace ORMs?,Is GraphQL owned by Facebook?,Who is behind GraphQL?,What is the GraphQL Foundation?
+bestPracticesQuestions: How does GraphQL affect my product’s performance?,Does GraphQL support offline usage?,What are the security concerns with GraphQL?,How can I set up authorization with GraphQL?,How does authentication work with GraphQL?,Is GraphQL the right fit for designing a microservice architecture?,How can I document my GraphQL API?
+specificationQuestions: What’s the best way to follow specification releases?,How can I contribute to the GraphQL specification?
+frontendQuestions: Does GraphQL replace Redux or other state management libraries?
 ---
 
 ## Why should I use GraphQL?
@@ -20,14 +24,6 @@ It depends on your use case, but in general, GraphQL has a few key features that
 
 You can try out GraphQL without rewriting your entire application. For instance, starting with a single HTTP request that wraps an existing REST call. Your [GraphQL schema](/learn/thinking-in-graphs/#shared-language) and [business domain model](/learn/thinking-in-graphs/#business-logic-layer) can expand gradually. We recommend focusing on one use case at first and only building the part of the schema needed for that. 
 
-## Is GraphQL a database language like SQL?
-
-No, but this is a common misconception.
-
-GraphQL is a specification typically used for remote client-server communications. Unlike SQL, GraphQL is agnostic to the data source(s) used to retrieve data and persist changes. Accessing and manipulating data is performed with arbitrary functions called [resolvers](/learn/execution/). GraphQL coordinates and aggregates the data from these resolver functions, then returns the result to the client. Generally, these resolver functions should delegate to a [business logic layer](/learn/thinking-in-graphs/#business-logic-layer) responsible for communicating with the various underlying data sources. These data sources could be remote APIs, databases, [local cache](/learn/caching/), and nearly anything else your programming language can access.
-
-For more information on how to get GraphQL to interact with your database, check out our [documentation on resolvers](/learn/execution/#root-fields-resolvers).
-
 ## Does GraphQL replace REST?
 
 No, not necessarily. They both handle APIs and can [serve similar purposes](/learn/thinking-in-graphs/#business-logic-layer) from a business perspective. GraphQL is often considered an alternative to REST, but it’s not a definitive replacement.
@@ -44,9 +40,13 @@ For more practical guides, visit the [How to GraphQL](https://www.howtographql.c
 
 Before you start your learning journey, make sure you know [what an API is](https://www.codenewbie.org/blogs/an-intro-to-apis) and how communication generally works between client and server.
 
-## Is GraphQL frontend or backend?
+## Is GraphQL a database language like SQL?
 
-Both. GraphQL specifies how you can [exchange information between client and server](https://www.howtographql.com/basics/3-big-picture/). This includes how the server can indicate [what data and operations are available](/learn/introspection/), how the client should [format requests](/learn/queries/), how the server should [execute these queries](/learn/execution/), and what the client will [receive in response](/learn/serving-over-http/#response).
+No, but this is a common misconception.
+
+GraphQL is a specification typically used for remote client-server communications. Unlike SQL, GraphQL is agnostic to the data source(s) used to retrieve data and persist changes. Accessing and manipulating data is performed with arbitrary functions called [resolvers](/learn/execution/). GraphQL coordinates and aggregates the data from these resolver functions, then returns the result to the client. Generally, these resolver functions should delegate to a [business logic layer](/learn/thinking-in-graphs/#business-logic-layer) responsible for communicating with the various underlying data sources. These data sources could be remote APIs, databases, [local cache](/learn/caching/), and nearly anything else your programming language can access.
+
+For more information on how to get GraphQL to interact with your database, check out our [documentation on resolvers](/learn/execution/#root-fields-resolvers).
 
 ## Is GraphQL only for React or JavaScript developers?
 
@@ -54,6 +54,14 @@ No, not at all. [GraphQL is a specification](https://spec.graphql.org/) that can
 
 It’s understandable why you’d think this, though. GraphQL was introduced at a [React conference](https://www.youtube.com/watch?v=9sc8Pyc51uU) and [GraphQL.js](/graphql-js/) is one of the most widely used implementations to date. We know this can be confusing, so we’re working to improve our documentation and add more code samples that aren’t written in JavaScript.
 
+## Is GraphQL frontend or backend?
+
+Both. GraphQL specifies how you can [exchange information between client and server](https://www.howtographql.com/basics/3-big-picture/). This includes how the server can indicate [what data and operations are available](/learn/introspection/), how the client should [format requests](/learn/queries/), how the server should [execute these queries](/learn/execution/), and what the client will [receive in response](/learn/serving-over-http/#response).
+
+## Does GraphQL use HTTP?
+
+<!-- TODO -->
+
 ## What is a GraphQL client and why would I use one?
 
 GraphQL clients can help you handle [queries, mutations,](/learn/queries/) and [subscriptions](https://spec.graphql.org/draft/#sec-Subscription) to a [GraphQL server](https://www.howtographql.com/advanced/1-server/). They use the underlying structure of a GraphQL API to automate certain processes. This includes batching, UI updates, build-time schema validation, and more.
@@ -62,20 +70,80 @@ A list of GraphQL clients in various languages is available on our [Code page](/
 
 You don't need a specific client to work with GraphQL, though. You might want to start out by [issuing GraphQL results with a regular HTTP client](/learn/serving-over-http/). Then later switch to a GraphQL-optimized client as your application grows in complexity.
 
+## Does GraphQL replace ORMs?
+
+No, GraphQL is a specification. It [doesn’t understand the concept of databases](#is-graphql-a-database-language-like-sql). There are, however, ORMs built specifically for GraphQL. A few of those are listed under the [Services section of our Code page](/code/#services). 
+
 ## Is GraphQL owned by Facebook?
 
 No, GraphQL is governed by the [GraphQL Foundation](#what-is-the-graphql-foundation).
 
 That said, the specification was originally developed at Facebook and [Facebook is a member](https://foundation.graphql.org/members/) of the GraphQL Foundation. You might notice that some of our [GitHub repositories](https://github.com/graphql/) still have the license listed under Facebook Inc. We're updating those and have already converted major projects, like [GraphiQL](https://github.com/graphql/graphiql/blob/main/LICENSE) and [DataLoader](https://github.com/graphql/dataloader/blob/master/LICENSE), to the the new copyright: "Copyright (c) 2020 GraphQL Contributors."
 
+## Who is behind GraphQL?
+
+Loads of people! The [GraphQL specification and all related projects](http://github.com/graphql/) are open source, so anyone is welcome to [contribute](#how-can-i-contribute-to-the-specification). That being said, there is a structure in place behind the repositories - particularly for resolving conflicts within the community and guiding technical decisions. 
+
+The [GraphQL Foundation](#what-is-the-graphql-foundation) provides most of the oversight for GraphQL and is made up of [representatives from 20 different companies](https://foundation.graphql.org/members/). There are also monthly virtual [GraphQL Working Group (WG)](https://github.com/graphql/graphql-wg) meetings. These meetings are operated by the GraphQL Foundation and designed to bring together maintainers of commonly used GraphQL libraries and tools, as well as significant contributors to the GraphQL community. While it tends to be mostly foundation members in attendance, the WG meetings are completely open. Anyone is able to join and [propose items to the agenda](https://github.com/graphql/graphql-wg/blob/master/agendas/). Additionally, GraphQL will soon have a Technical Steering Committee (TSC) to advise on implementation details. More on that coming soon.
+
+If this is confusing, don’t worry - there’s a lot going on. To get a more visual high-level overview, check out the [GraphQL Landscape](https://landscape.graphql.org/).
+
 ## What is the GraphQL Foundation?
 
 The [GraphQL Foundation](https://foundation.graphql.org/faq/) is a neutral foundation that provides governance for GraphQL. This includes vendor-neutral oversight of open-source repositories, funding, events, and more. It's hosted under the [Linux Foundation](https://www.linuxfoundation.org/) and consists of [representatives from dozens of different companies](https://foundation.graphql.org/members/). The idea is that it’s an impartial and open home for the GraphQL community.
 
 You can find out more by visiting [foundation.graphql.org](https://foundation.graphql.org/).
 
+## How does GraphQL affect my product’s performance?
+
+<!-- TODO -->
+
+## Does GraphQL support offline usage?
+
+No, or at least not natively. But there are [GraphQL clients](#what-is-a-graphql-client-and-why-would-i-need-one) that enable you to build offline-first through caching, holding your mutations in a queue, service workers, or another feature designed to perform data operations while offline. 
+
+You can find a [list of GraphQL clients on our Code page](/code/#graphql-clients).
+
+## What are the security concerns with GraphQL?
+
+<!-- TODO -->
+
+## How can I set up authorization with GraphQL?
+
+As tempting as it is to define your authorization logic in your GraphQL implementation, we recommend enforcing authorization behavior in the [business logic layer](/learn/thinking-in-graphs/#business-logic-layer). That way, you have a single source of truth for authorization. 
+
+For a more detailed explanation, go to our [Authorization documentation](/learn/authorization/).
+
+## How does authentication work with GraphQL?
+
+There’s nothing special about it within the specification, but you can implement authentication with common patterns, such as [OAuth](https://oauth.net/) or [JWT](https://jwt.io/). Some [GraphQL libraries](/code/) include a specific protocol for authentication as well. Although if you’re working with a pipeline model, we recommend that [GraphQL should be placed after all authentication middleware](/learn/serving-over-http/#web-request-pipeline).
+
+If you’re using [GraphQL.js](/graphql-js/) to build your API server, we have documentation on [handling authentication with Express middleware](/graphql-js/authentication-and-express-middleware/).
+
+## Is GraphQL the right fit for designing a microservice architecture?
+
+Yes, it can be. If you’re integrating GraphQL into your microservice architecture, we’d recommend having one GraphQL schema as an API gateway rather than having your client talk to multiple GraphQL services. This way, you can split your backend into microservices, but then still aggregate all of your data to the frontend from a single API.
+
+There are many ways to create an API gateway, but the benefit of using GraphQL is that you can take advantage of features like [caching](/learn/caching/), request budgeting, and planning out query schedules.
+
+## How can I document my GraphQL API?
+
+One of the benefits of GraphQL is that it is inherently self-documenting. This means that when you use an interactive tool like [GraphiQL](https://github.com/graphql/graphiql), you’re able to explore what data is exposed by your GraphQL API. This includes the [fields](/learn/queries/#fields), [types](/learn/schema/#type-system), and more. You can also add a [`description` field](https://spec.graphql.org/draft/#sec-Documentation) to provide supplementary notes about your endpoint. 
+
+For many, this provides sufficient API reference documentation. But it doesn’t reduce the need for other forms of documentation, such as guides that explain how the general concepts tie into your specific use case.
+
+## What’s the best way to follow specification releases?
+
+The latest working draft release of the GraphQL specification can be found at [spec.graphql.org/draft](https://spec.graphql.org/draft/). Previous editions can also be found at permalinks that match their [release tag](https://github.com/graphql/graphql-spec/releases).
+
 ## How can I contribute to the GraphQL specification?
 
 GraphQL is still evolving and contributions are very welcome! The specification (including the [latest working draft](https://spec.graphql.org/)) is open source. [Contributor guidelines](https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md) are available on GitHub.
 
 There are more ways to get involved with GraphQL beyond the specification though. Updating the content on [this website and the documentation](https://github.com/graphql/graphql.github.io), for example. Or contributing to [graphql-js](https://github.com/graphql/graphql-js), [express-graphql](https://github.com/graphql/express-graphql), [GraphiQL](https://github.com/graphql/graphiql), or [one of the many other projects](https://github.com/graphql/) maintained by the [GraphQL Foundation](#what-is-the-graphql-foundation). 
+
+## Does GraphQL replace Redux or other state management libraries?
+
+No, GraphQL isn’t a state management library - but it can reduce the need for one.
+
+One benefit of state management libraries like Redux is that they can manipulate API responses into a format that your application understands. With GraphQL, you have control over [what data you request](/learn/queries/#fields) and typically results are formatted in a client-friendly way by virtue of the graph design. So this benefit is already built-in. Many [client libraries](https://graphql.org/code/#graphql-clients) can also be used to manage state and have features like caching built-in. You may still decide to implement a state management library, but using it to format response data is generally not necessary.
diff --git a/src/templates/doc.tsx b/src/templates/doc.tsx
index d179668dfa..054278a9a3 100644
--- a/src/templates/doc.tsx
+++ b/src/templates/doc.tsx
@@ -21,7 +21,7 @@ const layoutMap: any = {
 const Blog = ({ data, pageContext }: Props) => {
   const {
     doc: {
-      frontmatter: { title, date, permalink, byline, guestBio, layout, questions },
+      frontmatter: { title, date, permalink, byline, guestBio, layout, gettingStartedQuestions, generalQuestions, bestPracticesQuestions, specificationQuestions, frontendQuestions },
       rawMarkdownBody,
     },
     nextDoc,
@@ -35,7 +35,11 @@ const Blog = ({ data, pageContext }: Props) => {
         permalink={permalink}
         byline={byline}
         guestBio={guestBio}
-        questions={questions}
+        gettingStartedQuestions={gettingStartedQuestions}
+        generalQuestions={generalQuestions}
+        bestPracticesQuestions={bestPracticesQuestions}
+        specificationQuestions={specificationQuestions}
+        frontendQuestions={frontendQuestions}
         rawMarkdownBody={rawMarkdownBody}
         nextDoc={nextDoc}
         sideBarData={pageContext.sideBarData}
@@ -56,7 +60,11 @@ export const query = graphql`
         guestBio
         sublinks
         layout
-        questions
+        gettingStartedQuestions
+        generalQuestions
+        bestPracticesQuestions
+        specificationQuestions
+        frontendQuestions
       }
       id
       rawMarkdownBody

From cbfabd93a799c957208a000b774108eb7e839169 Mon Sep 17 00:00:00 2001
From: carolstran <carolynstransky@gmail.com>
Date: Wed, 25 Nov 2020 11:33:00 +0100
Subject: [PATCH 03/11] Smol tweaks

---
 src/content/faq/General.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index 84a6aa6a44..40779cc602 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -82,9 +82,9 @@ That said, the specification was originally developed at Facebook and [Facebook
 
 ## Who is behind GraphQL?
 
-Loads of people! The [GraphQL specification and all related projects](http://github.com/graphql/) are open source, so anyone is welcome to [contribute](#how-can-i-contribute-to-the-specification). That being said, there is a structure in place behind the repositories - particularly for resolving conflicts within the community and guiding technical decisions. 
+Many people! The [GraphQL specification and all related projects](http://github.com/graphql/) are open source, so anyone is welcome to [contribute](#how-can-i-contribute-to-the-specification). That said, there is a structure in place behind the repositories - particularly for resolving conflicts within the community and guiding technical decisions. 
 
-The [GraphQL Foundation](#what-is-the-graphql-foundation) provides most of the oversight for GraphQL and is made up of [representatives from 20 different companies](https://foundation.graphql.org/members/). There are also monthly virtual [GraphQL Working Group (WG)](https://github.com/graphql/graphql-wg) meetings. These meetings are operated by the GraphQL Foundation and designed to bring together maintainers of commonly used GraphQL libraries and tools, as well as significant contributors to the GraphQL community. While it tends to be mostly foundation members in attendance, the WG meetings are completely open. Anyone is able to join and [propose items to the agenda](https://github.com/graphql/graphql-wg/blob/master/agendas/). Additionally, GraphQL will soon have a Technical Steering Committee (TSC) to advise on implementation details. More on that coming soon.
+The [GraphQL Foundation](#what-is-the-graphql-foundation) provides most of the oversight for GraphQL and is made up of [representatives from dozens of different companies](https://foundation.graphql.org/members/). There are also monthly virtual [GraphQL Working Group (WG)](https://github.com/graphql/graphql-wg) meetings. These meetings are operated by the GraphQL Foundation and designed to bring together maintainers of commonly used GraphQL libraries and tools, as well as significant contributors to the GraphQL community. While it tends to be mostly foundation members in attendance, the WG meetings are completely open. Anyone is able to join and [propose items to the agenda](https://github.com/graphql/graphql-wg/blob/master/agendas/). Additionally, it was announed in the [November 2020 WG meeting](https://www.youtube.com/watch?v=UybZp9O24Ow) that GraphQL will have a Technical Steering Committee (TSC) going forward. More on that coming soon.
 
 If this is confusing, don’t worry - there’s a lot going on. To get a more visual high-level overview, check out the [GraphQL Landscape](https://landscape.graphql.org/).
 

From f4cc783005a0291f5ed59b5b011e711cf52c0335 Mon Sep 17 00:00:00 2001
From: carolstran <carolynstransky@gmail.com>
Date: Wed, 25 Nov 2020 17:16:44 +0100
Subject: [PATCH 04/11] Tweak existing answers, add subscription question

---
 src/content/faq/General.md | 50 ++++++++++++++++++++++----------------
 1 file changed, 29 insertions(+), 21 deletions(-)

diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index 1804893f0c..3e83dc5cd7 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -4,9 +4,9 @@ layout: faq
 category: General
 permalink: /faq/
 gettingStartedQuestions: Why should I use GraphQL?,Does GraphQL replace REST?,How can I learn GraphQL?,Is GraphQL a database language like SQL?,Is GraphQL only for React or JavaScript developers?
-generalQuestions: Is GraphQL frontend or backend?,Does GraphQL use HTTP?,What is a GraphQL client and why would I use one?,Does GraphQL replace ORMs?,Is GraphQL owned by Facebook?,Who is behind GraphQL?,What is the GraphQL Foundation?
+generalQuestions: Is GraphQL frontend or backend?,Does GraphQL use HTTP?,What is a GraphQL client and why would I use one?,Where is the documentation for subscriptions?,Does GraphQL replace ORMs?,Is GraphQL owned by Facebook?,Who is behind GraphQL?,What is the GraphQL Foundation?
 bestPracticesQuestions: How does GraphQL affect my product’s performance?,Does GraphQL support offline usage?,What are the security concerns with GraphQL?,How can I set up authorization with GraphQL?,How does authentication work with GraphQL?,Is GraphQL the right fit for designing a microservice architecture?,How can I document my GraphQL API?
-specificationQuestions: What’s the best way to follow specification releases?,How can I contribute to the GraphQL specification?
+specificationQuestions: What is the best way to follow specification releases?,How can I contribute to the GraphQL specification?
 frontendQuestions: Does GraphQL replace Redux or other state management libraries?
 ---
 
@@ -22,11 +22,7 @@ It depends on your use case, but in general, GraphQL has a few key features that
 
 [Our homepage](/) outlines even more reasons to use GraphQL.
 
-<<<<<<< HEAD
 You can try out GraphQL without rewriting your entire application. For instance, starting with a single HTTP request that wraps an existing REST call. Your [GraphQL schema](/learn/thinking-in-graphs/#shared-language) and [business domain model](/learn/thinking-in-graphs/#business-logic-layer) can expand gradually. We recommend focusing on one use case at first and only building the part of the schema needed for that. 
-=======
-You can try out GraphQL without rewriting your entire application. For example, starting with a single HTTP request that wraps an existing REST call. Your [GraphQL schema](/learn/thinking-in-graphs/#shared-language) and [business domain model](/learn/thinking-in-graphs/#business-logic-layer) can expand gradually. We recommend focusing on one use case at first and only building the part of the schema needed for that. 
->>>>>>> 43725c45eff1ea78323b3b0e71962e6f67a444d6
 
 ## Does GraphQL replace REST?
 
@@ -74,9 +70,15 @@ A list of GraphQL clients in various languages is available on our [Code page](/
 
 You don't need a specific client to work with GraphQL, though. You might want to start out by [issuing GraphQL results with a regular HTTP client](/learn/serving-over-http/). Then later switch to a GraphQL-optimized client as your application grows in complexity.
 
+## Where is the documentation for subscriptions?
+
+It's not on this website yet, but we're working on it. If you'd like to help create these guides, please [let us know](https://github.com/graphql/graphql.github.io/issues/new). 
+
+For now, the specification includes details for [how to write and execute subscriptions](https://spec.graphql.org/draft/#sec-Subscription).
+
 ## Does GraphQL replace ORMs?
 
-No, GraphQL is a specification. It [doesn’t understand the concept of databases](#is-graphql-a-database-language-like-sql). There are, however, ORMs built specifically for GraphQL. A few of those are listed under the [Services section of our Code page](/code/#services). 
+No, GraphQL is a specification typically used for remote client-server communications. It's [agnostic to the data source(s) used](#is-graphql-a-database-language-like-sql) and doesn’t implement an object-relational mapping technique. But there are ORMs built specifically for GraphQL. A few of those are listed under the [Services section of our Code page](/code/#services). 
 
 ## Is GraphQL owned by Facebook?
 
@@ -86,11 +88,15 @@ That said, the specification was originally developed at Facebook and [Facebook
 
 ## Who is behind GraphQL?
 
-Many people! The [GraphQL specification and all related projects](http://github.com/graphql/) are open source, so anyone is welcome to [contribute](#how-can-i-contribute-to-the-specification). That said, there is a structure in place behind the repositories - particularly for resolving conflicts within the community and guiding technical decisions. 
+Many people! The [GraphQL specification and all related projects](http://github.com/graphql/) are open source, so anyone is welcome to [contribute](#how-can-i-contribute-to-the-specification). That said, there is a structure in place behind the repositories. This exists to resolve conflicts within the community and guiding technical decisions.
 
-The [GraphQL Foundation](#what-is-the-graphql-foundation) provides most of the oversight for GraphQL and is made up of [representatives from dozens of different companies](https://foundation.graphql.org/members/). There are also monthly virtual [GraphQL Working Group (WG)](https://github.com/graphql/graphql-wg) meetings. These meetings are operated by the GraphQL Foundation and designed to bring together maintainers of commonly used GraphQL libraries and tools, as well as significant contributors to the GraphQL community. While it tends to be mostly foundation members in attendance, the WG meetings are completely open. Anyone is able to join and [propose items to the agenda](https://github.com/graphql/graphql-wg/blob/master/agendas/). Additionally, it was announed in the [November 2020 WG meeting](https://www.youtube.com/watch?v=UybZp9O24Ow) that GraphQL will have a Technical Steering Committee (TSC) going forward. More on that coming soon.
+The [GraphQL Foundation](#what-is-the-graphql-foundation) provides most of the oversight for GraphQL. It's made up of [representatives from dozens of different companies](https://foundation.graphql.org/members/). 
 
-If this is confusing, don’t worry - there’s a lot going on. To get a more visual high-level overview, check out the [GraphQL Landscape](https://landscape.graphql.org/).
+There are also monthly virtual [GraphQL Working Group (WG)](https://github.com/graphql/graphql-wg) meetings managed by the GraphQL Foundation. These meetings are designed to bring together maintainers of commonly used GraphQL libraries and tools, as well as significant contributors to the GraphQL community. While it tends to be mostly foundation members in attendance, the WG meetings are completely open. Anyone is able to join and [propose items to the agenda](https://github.com/graphql/graphql-wg/blob/master/agendas/). 
+
+In the [November 2020 WG meeting](https://www.youtube.com/watch?v=UybZp9O24Ow), it was announced that GraphQL will have a Technical Steering Committee (TSC) going forward. More on that coming soon.
+
+If this is confusing, don’t worry - there’s a lot going on. To get a more visual, high-level overview, check out the [GraphQL Landscape](https://landscape.graphql.org/).
 
 ## What is the GraphQL Foundation?
 
@@ -104,9 +110,9 @@ You can find out more by visiting [foundation.graphql.org](https://foundation.gr
 
 ## Does GraphQL support offline usage?
 
-No, or at least not natively. But there are [GraphQL clients](#what-is-a-graphql-client-and-why-would-i-need-one) that enable you to build offline-first through caching, holding your mutations in a queue, service workers, or another feature designed to perform data operations while offline. 
+No, or at least not natively. But there are [GraphQL clients](#what-is-a-graphql-client-and-why-would-i-need-one) that enable you to build offline-first. They use features designed to perform data operations while offline, such as caching and service workers.
 
-You can find a [list of GraphQL clients on our Code page](/code/#graphql-clients).
+You can find a list of GraphQL clients in various languages on our [Code page](/code/).
 
 ## What are the security concerns with GraphQL?
 
@@ -114,31 +120,33 @@ You can find a [list of GraphQL clients on our Code page](/code/#graphql-clients
 
 ## How can I set up authorization with GraphQL?
 
-As tempting as it is to define your authorization logic in your GraphQL implementation, we recommend enforcing authorization behavior in the [business logic layer](/learn/thinking-in-graphs/#business-logic-layer). That way, you have a single source of truth for authorization. 
+We recommend enforcing authorization behavior in the [business logic layer](/learn/thinking-in-graphs/#business-logic-layer). That way, you have a single source of truth for authorization. 
 
 For a more detailed explanation, go to our [Authorization documentation](/learn/authorization/).
 
 ## How does authentication work with GraphQL?
 
-There’s nothing special about it within the specification, but you can implement authentication with common patterns, such as [OAuth](https://oauth.net/) or [JWT](https://jwt.io/). Some [GraphQL libraries](/code/) include a specific protocol for authentication as well. Although if you’re working with a pipeline model, we recommend that [GraphQL should be placed after all authentication middleware](/learn/serving-over-http/#web-request-pipeline).
+You can implement authentication with common patterns, such as [OAuth](https://oauth.net/) or [JWT](https://jwt.io/). There’s nothing special about authentication within the GraphQL specification. 
+
+Some [GraphQL libraries](/code/#language-support) include a specific protocol for authentication as well. Although if you’re working with a pipeline model, we recommend that [GraphQL be placed after all authentication middleware](/learn/serving-over-http/#web-request-pipeline).
 
 If you’re using [GraphQL.js](/graphql-js/) to build your API server, we have documentation on [handling authentication with Express middleware](/graphql-js/authentication-and-express-middleware/).
 
 ## Is GraphQL the right fit for designing a microservice architecture?
 
-Yes, it can be. If you’re integrating GraphQL into your microservice architecture, we’d recommend having one GraphQL schema as an API gateway rather than having your client talk to multiple GraphQL services. This way, you can split your backend into microservices, but then still aggregate all of your data to the frontend from a single API.
+Yes, it can be. If you’re integrating GraphQL into your microservice architecture, we’d recommend having one GraphQL schema as an API gateway rather than having your client talk to multiple GraphQL services. This way, you can split your backend into microservices, but then still aggregate all your data to the frontend from a single API.
 
-There are many ways to create an API gateway, but the benefit of using GraphQL is that you can take advantage of features like [caching](/learn/caching/), request budgeting, and planning out query schedules.
+There are many ways to create an API gateway. The benefit of using GraphQL is that you can take advantage of features like [caching](/learn/caching/), request budgeting, and planning out query schedules.
 
 ## How can I document my GraphQL API?
 
-One of the benefits of GraphQL is that it is inherently self-documenting. This means that when you use an interactive tool like [GraphiQL](https://github.com/graphql/graphiql), you’re able to explore what data is exposed by your GraphQL API. This includes the [fields](/learn/queries/#fields), [types](/learn/schema/#type-system), and more. You can also add a [`description` field](https://spec.graphql.org/draft/#sec-Documentation) to provide supplementary notes about your endpoint. 
+One of the benefits of GraphQL is that it's inherently self-documenting. This means that when you use an interactive tool like [GraphiQL](https://github.com/graphql/graphiql), you’re able to explore what data is exposed by your GraphQL API. This includes the [fields](/learn/queries/#fields), [types](/learn/schema/#type-system), and more. You can also add a [description field](https://spec.graphql.org/draft/#sec-Documentation) to provide supplementary notes about your endpoint. 
 
-For many, this provides sufficient API reference documentation. But it doesn’t reduce the need for other forms of documentation, such as guides that explain how the general concepts tie into your specific use case.
+For many, this provides enough API reference documentation. But it doesn’t reduce the need for other forms of documentation. You'll likely still need to create guides that explain how the general concepts tie into your specific use case.
 
-## What’s the best way to follow specification releases?
+## What is the best way to follow specification releases?
 
-The latest working draft release of the GraphQL specification can be found at [spec.graphql.org/draft](https://spec.graphql.org/draft/). Previous editions can also be found at permalinks that match their [release tag](https://github.com/graphql/graphql-spec/releases).
+The latest working draft release of the GraphQL specification can be found at [spec.graphql.org/draft](https://spec.graphql.org/draft/). Previous editions are also available at permalinks that match their [release tag](https://github.com/graphql/graphql-spec/releases).
 
 ## How can I contribute to the GraphQL specification?
 
@@ -150,4 +158,4 @@ There are more ways to get involved with GraphQL beyond the specification though
 
 No, GraphQL isn’t a state management library - but it can reduce the need for one.
 
-One benefit of state management libraries like Redux is that they can manipulate API responses into a format that your application understands. With GraphQL, you have control over [what data you request](/learn/queries/#fields) and typically results are formatted in a client-friendly way by virtue of the graph design. So this benefit is already built-in. Many [client libraries](https://graphql.org/code/#graphql-clients) can also be used to manage state and have features like caching built-in. You may still decide to implement a state management library, but using it to format response data is generally not necessary.
+One benefit of state management libraries like Redux is that they can manipulate API responses into a format that your application understands. With GraphQL, you have control over [what data you request](/learn/queries/#fields) and typically results are formatted in a client-friendly way by the graph design. So this benefit is already built-in. Many [client libraries](#what-is-a-graphql-client-and-why-would-i-need-one) can also be used to manage state and have features like caching built-in. You may still decide to implement a state management library, but using it to format response data is generally not necessary.

From df2745afb729e91ebde1f914413b818509a187b6 Mon Sep 17 00:00:00 2001
From: carolstran <carolynstransky@gmail.com>
Date: Thu, 26 Nov 2020 07:32:20 +0100
Subject: [PATCH 05/11] Add missing answers

---
 src/content/faq/General.md | 31 +++++++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index 3e83dc5cd7..f320b4e7e0 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -5,7 +5,7 @@ category: General
 permalink: /faq/
 gettingStartedQuestions: Why should I use GraphQL?,Does GraphQL replace REST?,How can I learn GraphQL?,Is GraphQL a database language like SQL?,Is GraphQL only for React or JavaScript developers?
 generalQuestions: Is GraphQL frontend or backend?,Does GraphQL use HTTP?,What is a GraphQL client and why would I use one?,Where is the documentation for subscriptions?,Does GraphQL replace ORMs?,Is GraphQL owned by Facebook?,Who is behind GraphQL?,What is the GraphQL Foundation?
-bestPracticesQuestions: How does GraphQL affect my product’s performance?,Does GraphQL support offline usage?,What are the security concerns with GraphQL?,How can I set up authorization with GraphQL?,How does authentication work with GraphQL?,Is GraphQL the right fit for designing a microservice architecture?,How can I document my GraphQL API?
+bestPracticesQuestions: How does GraphQL affect my product’s performance?,Is GraphQL scalable?,Does GraphQL support offline usage?,What are the security concerns with GraphQL?,How can I set up authorization with GraphQL?,How does authentication work with GraphQL?,Is GraphQL the right fit for designing a microservice architecture?,How does versioning work in GraphQL?,How can I document my GraphQL API?
 specificationQuestions: What is the best way to follow specification releases?,How can I contribute to the GraphQL specification?
 frontendQuestions: Does GraphQL replace Redux or other state management libraries?
 ---
@@ -60,7 +60,11 @@ Both. GraphQL specifies how you can [exchange information between client and ser
 
 ## Does GraphQL use HTTP?
 
-<!-- TODO -->
+Yes, [GraphQL is typically served over HTTP](/learn/best-practices/#http). This is largely due to 
+
+More guidelines for how to set up a GraphQL server to operate over HTTP are available in our [Serving over HTTP](/learn/serving-over-http/) documentation. 
+
+While HTTP is the most common choice for client-server protocol, it’s not the only one. GraphQL is agnostic to the transport layer. So for example, you could use [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) for GraphQL subscriptions instead of HTTP to consume realtime data. 
 
 ## What is a GraphQL client and why would I use one?
 
@@ -106,7 +110,14 @@ You can find out more by visiting [foundation.graphql.org](https://foundation.gr
 
 ## How does GraphQL affect my product’s performance?
 
-<!-- TODO -->
+GraphQL is designed to be clean. Every field on every type has a focused, single-purpose function for resolving that value. Also, instead of trying to handle data parsing on the client, [GraphQL moves that logic to the server](/learn/best-practices/#server-side-batching-caching). As a result, there are some inherent performance benefits, such as minimizing over-fetching and generally making [fewer roundtrips to the server](/learn/queries/#fields) to retrieve your data.
+
+Some additional performance considerations should be taken into account when building out your GraphQL implementation, though. For example, it’s possible for a GraphQL service to be ‘chatty’ and repeatedly load data from your database. This is commonly solved by [implementing a batching technique](/learn/best-practices/#server-side-batching-caching) or [utilizing a tool like DataLoader](https://github.com/graphql/dataloader). 
+
+## Is GraphQL scalable?
+
+Yes, but only if you scale it. GraphQL comes with some [built-in performance boosts](#how-does-graphql-affect-my-product-s-performance) that help. Once you push it to production though, your team is responsible for scaling it across instances and monitoring performance.  
+
 
 ## Does GraphQL support offline usage?
 
@@ -116,7 +127,11 @@ You can find a list of GraphQL clients in various languages on our [Code page](/
 
 ## What are the security concerns with GraphQL?
 
-<!-- TODO -->
+Most of the security concerns associated with GraphQL are typical for any API or service. Think SQL injections, Denial of Service (DoS) attacks, someone abusing flawed authentication, etc. But there are also some attacks specific to GraphQL. For example, [batching attacks](https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html#batching-attacks) can occur as a result of GraphQL allowing you to batch multiple queries or requests for multiple object instances in a single network call. 
+
+No matter the concern, it’s important to be proactive. Fortunately, there are many approaches to securing your GraphQL server. Some of these approaches include using a timeout, setting a maximum depth for queries, and throttling queries based on the server time it needs to complete. 
+
+For an overview of common security concerns and how to address them, check out the [Security tutorial on How to GraphQL](https://www.howtographql.com/advanced/4-security/) and [OWASP’s GraphQL Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html).
 
 ## How can I set up authorization with GraphQL?
 
@@ -138,6 +153,14 @@ Yes, it can be. If you’re integrating GraphQL into your microservice architect
 
 There are many ways to create an API gateway. The benefit of using GraphQL is that you can take advantage of features like [caching](/learn/caching/), request budgeting, and planning out query schedules.
 
+## How does versioning work in GraphQL?
+
+There’s nothing that will prevent a GraphQL service from being versioned like any other REST API. That said, GraphQL inherently avoids versioning. 
+
+Instead, GraphQL provides the tools to continually build and evolve your schema. For example, GraphQL only returns the data that’s explicitly requested. This means that you can add new features (and all of the associated types and fields) without creating a breaking change.
+
+You can read more about [how versioning works in GraphQL](/learn/best-practices/#versioning) in our Best Practices section.
+
 ## How can I document my GraphQL API?
 
 One of the benefits of GraphQL is that it's inherently self-documenting. This means that when you use an interactive tool like [GraphiQL](https://github.com/graphql/graphiql), you’re able to explore what data is exposed by your GraphQL API. This includes the [fields](/learn/queries/#fields), [types](/learn/schema/#type-system), and more. You can also add a [description field](https://spec.graphql.org/draft/#sec-Documentation) to provide supplementary notes about your endpoint. 

From 99c213d4e6d2936acfe5f7d2fb52f16b06a28ef1 Mon Sep 17 00:00:00 2001
From: carolstran <carolynstransky@gmail.com>
Date: Thu, 26 Nov 2020 08:12:02 +0100
Subject: [PATCH 06/11] Fix sentence structure

---
 src/content/faq/General.md | 25 +++++++++++--------------
 1 file changed, 11 insertions(+), 14 deletions(-)

diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index f320b4e7e0..5a297e4a2b 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -60,11 +60,9 @@ Both. GraphQL specifies how you can [exchange information between client and ser
 
 ## Does GraphQL use HTTP?
 
-Yes, [GraphQL is typically served over HTTP](/learn/best-practices/#http). This is largely due to 
+Yes, [GraphQL is typically served over HTTP](/learn/best-practices/#http). This is largely due to how pervasive the HTTP protocol is in our industry. But it helps that you try out GraphQL by creating [a single HTTP request](#why-should-i-use-graphql). Guidelines for setting up a GraphQL server to operate over HTTP are available in our [Serving over HTTP](/learn/serving-over-http/) documentation. 
 
-More guidelines for how to set up a GraphQL server to operate over HTTP are available in our [Serving over HTTP](/learn/serving-over-http/) documentation. 
-
-While HTTP is the most common choice for client-server protocol, it’s not the only one. GraphQL is agnostic to the transport layer. So for example, you could use [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) for GraphQL subscriptions instead of HTTP to consume realtime data. 
+While HTTP is the most common choice for client-server protocol, it’s not the only one. GraphQL is agnostic to the transport layer. So, for example, you could use [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) for GraphQL subscriptions instead of HTTP to consume realtime data. 
 
 ## What is a GraphQL client and why would I use one?
 
@@ -76,9 +74,9 @@ You don't need a specific client to work with GraphQL, though. You might want to
 
 ## Where is the documentation for subscriptions?
 
-It's not on this website yet, but we're working on it. If you'd like to help create these guides, please [let us know](https://github.com/graphql/graphql.github.io/issues/new). 
+It's not on this website yet, but we're working on it. For now, the specification includes details for [how to write and execute subscriptions](https://spec.graphql.org/draft/#sec-Subscription). 
 
-For now, the specification includes details for [how to write and execute subscriptions](https://spec.graphql.org/draft/#sec-Subscription).
+If you'd like to help write guides on subscriptions, please [let us know](https://github.com/graphql/graphql.github.io/issues/new). 
 
 ## Does GraphQL replace ORMs?
 
@@ -110,14 +108,15 @@ You can find out more by visiting [foundation.graphql.org](https://foundation.gr
 
 ## How does GraphQL affect my product’s performance?
 
-GraphQL is designed to be clean. Every field on every type has a focused, single-purpose function for resolving that value. Also, instead of trying to handle data parsing on the client, [GraphQL moves that logic to the server](/learn/best-practices/#server-side-batching-caching). As a result, there are some inherent performance benefits, such as minimizing over-fetching and generally making [fewer roundtrips to the server](/learn/queries/#fields) to retrieve your data.
+With GraphQL, every field on every type has a focused, single-purpose function for resolving that value. Also, instead of trying to handle data parsing on the client, [GraphQL moves that logic to the server](/learn/best-practices/#server-side-batching-caching). As a result, there are some inherent performance benefits. Minimizing over-fetching and making [fewer roundtrips to the server](/learn/queries/#fields) are two of them.
 
-Some additional performance considerations should be taken into account when building out your GraphQL implementation, though. For example, it’s possible for a GraphQL service to be ‘chatty’ and repeatedly load data from your database. This is commonly solved by [implementing a batching technique](/learn/best-practices/#server-side-batching-caching) or [utilizing a tool like DataLoader](https://github.com/graphql/dataloader). 
+Other performance factors should be considered when building out your GraphQL implementation. For example, it’s possible for a GraphQL service to be ‘chatty’ and repeatedly load data from your database. This is commonly solved by [implementing a batching technique](/learn/best-practices/#server-side-batching-caching) or [utilizing a tool like DataLoader](https://github.com/graphql/dataloader). 
 
 ## Is GraphQL scalable?
 
-Yes, but only if you scale it. GraphQL comes with some [built-in performance boosts](#how-does-graphql-affect-my-product-s-performance) that help. Once you push it to production though, your team is responsible for scaling it across instances and monitoring performance.  
+Yes, if you scale it. 
 
+GraphQL comes with some [built-in performance boosts](#how-does-graphql-affect-my-product-s-performance) that can help. But once you push it to production, you're responsible for scaling it across instances and monitoring performance.
 
 ## Does GraphQL support offline usage?
 
@@ -127,9 +126,9 @@ You can find a list of GraphQL clients in various languages on our [Code page](/
 
 ## What are the security concerns with GraphQL?
 
-Most of the security concerns associated with GraphQL are typical for any API or service. Think SQL injections, Denial of Service (DoS) attacks, someone abusing flawed authentication, etc. But there are also some attacks specific to GraphQL. For example, [batching attacks](https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html#batching-attacks) can occur as a result of GraphQL allowing you to batch multiple queries or requests for multiple object instances in a single network call. 
+Most of the security concerns associated with GraphQL are typical for any API or service. A few examples: SQL injections, Denial of Service (DoS) attacks, or someone abusing flawed authentication. But there are also some attacks specific to GraphQL. For instance, [batching attacks](https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html#batching-attacks). These attacks can happen as a result of GraphQL allowing you to batch multiple queries (or requests for multiple object instances) in a single network call. 
 
-No matter the concern, it’s important to be proactive. Fortunately, there are many approaches to securing your GraphQL server. Some of these approaches include using a timeout, setting a maximum depth for queries, and throttling queries based on the server time it needs to complete. 
+No matter the concern, it’s important to be proactive. There are many ways to securing your GraphQL server. Using a timeout, setting a maximum depth for queries, and throttling queries based on the server time it needs to complete are all potential approaches. 
 
 For an overview of common security concerns and how to address them, check out the [Security tutorial on How to GraphQL](https://www.howtographql.com/advanced/4-security/) and [OWASP’s GraphQL Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html).
 
@@ -155,9 +154,7 @@ There are many ways to create an API gateway. The benefit of using GraphQL is th
 
 ## How does versioning work in GraphQL?
 
-There’s nothing that will prevent a GraphQL service from being versioned like any other REST API. That said, GraphQL inherently avoids versioning. 
-
-Instead, GraphQL provides the tools to continually build and evolve your schema. For example, GraphQL only returns the data that’s explicitly requested. This means that you can add new features (and all of the associated types and fields) without creating a breaking change.
+There’s nothing that will prevent a GraphQL service from being versioned like any other REST API. That said, GraphQL avoids versioning by design. Instead, GraphQL provides the tools to continually build and evolve your schema. For example, GraphQL only returns the data that’s explicitly requested. This means that you can add new features (and all the associated types and fields) without creating a breaking change.
 
 You can read more about [how versioning works in GraphQL](/learn/best-practices/#versioning) in our Best Practices section.
 

From d8ea4abce1f6b0ce3db6d04772f9873816ceb0b3 Mon Sep 17 00:00:00 2001
From: carolstran <carolynstransky@gmail.com>
Date: Thu, 26 Nov 2020 11:47:05 +0100
Subject: [PATCH 07/11] Move around some questions

---
 src/content/faq/General.md | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index 5a297e4a2b..d93c3070e5 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -4,9 +4,9 @@ layout: faq
 category: General
 permalink: /faq/
 gettingStartedQuestions: Why should I use GraphQL?,Does GraphQL replace REST?,How can I learn GraphQL?,Is GraphQL a database language like SQL?,Is GraphQL only for React or JavaScript developers?
-generalQuestions: Is GraphQL frontend or backend?,Does GraphQL use HTTP?,What is a GraphQL client and why would I use one?,Where is the documentation for subscriptions?,Does GraphQL replace ORMs?,Is GraphQL owned by Facebook?,Who is behind GraphQL?,What is the GraphQL Foundation?
-bestPracticesQuestions: How does GraphQL affect my product’s performance?,Is GraphQL scalable?,Does GraphQL support offline usage?,What are the security concerns with GraphQL?,How can I set up authorization with GraphQL?,How does authentication work with GraphQL?,Is GraphQL the right fit for designing a microservice architecture?,How does versioning work in GraphQL?,How can I document my GraphQL API?
-specificationQuestions: What is the best way to follow specification releases?,How can I contribute to the GraphQL specification?
+generalQuestions: Is GraphQL frontend or backend?,Does GraphQL use HTTP?,How does GraphQL affect my product’s performance?,What is a GraphQL client and why would I use one?,Does GraphQL replace ORMs?,Is GraphQL owned by Facebook?,Who is behind GraphQL?,What is the GraphQL Foundation?
+bestPracticesQuestions: Is GraphQL scalable?,Does GraphQL support offline usage?,What are the security concerns with GraphQL?,How can I set up authorization with GraphQL?,How does authentication work with GraphQL?,Is GraphQL the right fit for designing a microservice architecture?,How does versioning work in GraphQL?,How can I document my GraphQL API?
+specificationQuestions: What is the best way to follow specification releases?,How can I contribute to the GraphQL specification?,Where is the documentation for subscriptions?
 frontendQuestions: Does GraphQL replace Redux or other state management libraries?
 ---
 
@@ -64,6 +64,12 @@ Yes, [GraphQL is typically served over HTTP](/learn/best-practices/#http). This
 
 While HTTP is the most common choice for client-server protocol, it’s not the only one. GraphQL is agnostic to the transport layer. So, for example, you could use [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) for GraphQL subscriptions instead of HTTP to consume realtime data. 
 
+## How does GraphQL affect my product’s performance?
+
+With GraphQL, every field on every type has a focused, single-purpose function for resolving that value. Also, instead of trying to handle data parsing on the client, [GraphQL moves that logic to the server](/learn/best-practices/#server-side-batching-caching). As a result, there are some inherent performance benefits. Minimizing over-fetching and making [fewer roundtrips to the server](/learn/queries/#fields) are two of them.
+
+Other performance factors should be considered when building out your GraphQL implementation. For example, it’s possible for a GraphQL service to be ‘chatty’ and repeatedly load data from your database. This is commonly solved by [implementing a batching technique](/learn/best-practices/#server-side-batching-caching) or [utilizing a tool like DataLoader](https://github.com/graphql/dataloader). 
+
 ## What is a GraphQL client and why would I use one?
 
 GraphQL clients can help you handle [queries, mutations,](/learn/queries/) and [subscriptions](https://spec.graphql.org/draft/#sec-Subscription) to a [GraphQL server](https://www.howtographql.com/advanced/1-server/). They use the underlying structure of a GraphQL API to automate certain processes. This includes batching, UI updates, build-time schema validation, and more.
@@ -72,12 +78,6 @@ A list of GraphQL clients in various languages is available on our [Code page](/
 
 You don't need a specific client to work with GraphQL, though. You might want to start out by [issuing GraphQL results with a regular HTTP client](/learn/serving-over-http/). Then later switch to a GraphQL-optimized client as your application grows in complexity.
 
-## Where is the documentation for subscriptions?
-
-It's not on this website yet, but we're working on it. For now, the specification includes details for [how to write and execute subscriptions](https://spec.graphql.org/draft/#sec-Subscription). 
-
-If you'd like to help write guides on subscriptions, please [let us know](https://github.com/graphql/graphql.github.io/issues/new). 
-
 ## Does GraphQL replace ORMs?
 
 No, GraphQL is a specification typically used for remote client-server communications. It's [agnostic to the data source(s) used](#is-graphql-a-database-language-like-sql) and doesn’t implement an object-relational mapping technique. But there are ORMs built specifically for GraphQL. A few of those are listed under the [Services section of our Code page](/code/#services). 
@@ -106,12 +106,6 @@ The [GraphQL Foundation](https://foundation.graphql.org/faq/) is a neutral found
 
 You can find out more by visiting [foundation.graphql.org](https://foundation.graphql.org/).
 
-## How does GraphQL affect my product’s performance?
-
-With GraphQL, every field on every type has a focused, single-purpose function for resolving that value. Also, instead of trying to handle data parsing on the client, [GraphQL moves that logic to the server](/learn/best-practices/#server-side-batching-caching). As a result, there are some inherent performance benefits. Minimizing over-fetching and making [fewer roundtrips to the server](/learn/queries/#fields) are two of them.
-
-Other performance factors should be considered when building out your GraphQL implementation. For example, it’s possible for a GraphQL service to be ‘chatty’ and repeatedly load data from your database. This is commonly solved by [implementing a batching technique](/learn/best-practices/#server-side-batching-caching) or [utilizing a tool like DataLoader](https://github.com/graphql/dataloader). 
-
 ## Is GraphQL scalable?
 
 Yes, if you scale it. 
@@ -174,6 +168,12 @@ GraphQL is still evolving and contributions are very welcome! The specification
 
 There are more ways to get involved with GraphQL beyond the specification though. Updating the content on [this website and the documentation](https://github.com/graphql/graphql.github.io), for example. Or contributing to [graphql-js](https://github.com/graphql/graphql-js), [express-graphql](https://github.com/graphql/express-graphql), [GraphiQL](https://github.com/graphql/graphiql), or [one of the many other projects](https://github.com/graphql/) maintained by the [GraphQL Foundation](#what-is-the-graphql-foundation). 
 
+## Where is the documentation for subscriptions?
+
+It's not on this website yet, but we're working on it. For now, the specification includes details for [how to write and execute subscriptions](https://spec.graphql.org/draft/#sec-Subscription). 
+
+If you'd like to help write guides on subscriptions, please [let us know](https://github.com/graphql/graphql.github.io/issues/new). 
+
 ## Does GraphQL replace Redux or other state management libraries?
 
 No, GraphQL isn’t a state management library - but it can reduce the need for one.

From 1ab34a1a46828340e7148c0a82a3d8c2a2cf5d48 Mon Sep 17 00:00:00 2001
From: Carolyn Stransky <hello@workwithcarolyn.com>
Date: Tue, 1 Dec 2020 18:51:32 +0100
Subject: [PATCH 08/11] Apply suggestions from Benjie's code review

Co-authored-by: Benjie Gillam <benjie@jemjie.com>
---
 src/content/faq/General.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index d93c3070e5..06b764539b 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -148,7 +148,7 @@ There are many ways to create an API gateway. The benefit of using GraphQL is th
 
 ## How does versioning work in GraphQL?
 
-There’s nothing that will prevent a GraphQL service from being versioned like any other REST API. That said, GraphQL avoids versioning by design. Instead, GraphQL provides the tools to continually build and evolve your schema. For example, GraphQL only returns the data that’s explicitly requested. This means that you can add new features (and all the associated types and fields) without creating a breaking change.
+There’s nothing that will prevent a GraphQL service from being versioned like any other REST API. That said, GraphQL avoids versioning by design. Instead, GraphQL provides the tools to continually build and evolve your schema. For example, GraphQL only returns the data that’s explicitly requested. This means that you can add new features (and all the associated types and fields) without creating a breaking change or bloating results for existing queries.
 
 You can read more about [how versioning works in GraphQL](/learn/best-practices/#versioning) in our Best Practices section.
 

From 403ca07cc20e8571899628ce51b7f71ffab740ab Mon Sep 17 00:00:00 2001
From: Carolyn <carolyn@carolyns-mbp.localdomain>
Date: Tue, 1 Dec 2020 18:52:28 +0100
Subject: [PATCH 09/11] Tweak text based on code review

---
 src/content/faq/General.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index 06b764539b..d154bcf681 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -94,7 +94,7 @@ Many people! The [GraphQL specification and all related projects](http://github.
 
 The [GraphQL Foundation](#what-is-the-graphql-foundation) provides most of the oversight for GraphQL. It's made up of [representatives from dozens of different companies](https://foundation.graphql.org/members/). 
 
-There are also monthly virtual [GraphQL Working Group (WG)](https://github.com/graphql/graphql-wg) meetings managed by the GraphQL Foundation. These meetings are designed to bring together maintainers of commonly used GraphQL libraries and tools, as well as significant contributors to the GraphQL community. While it tends to be mostly foundation members in attendance, the WG meetings are completely open. Anyone is able to join and [propose items to the agenda](https://github.com/graphql/graphql-wg/blob/master/agendas/). 
+There are also monthly virtual [GraphQL Working Group (WG)](https://github.com/graphql/graphql-wg) meetings managed by the GraphQL Foundation. These meetings are designed to bring together maintainers of commonly used GraphQL libraries and tools, as well as significant contributors to the GraphQL community. The WG meetings are completely open. Anyone is able to join and [propose items to the agenda](https://github.com/graphql/graphql-wg/blob/master/agendas/). 
 
 In the [November 2020 WG meeting](https://www.youtube.com/watch?v=UybZp9O24Ow), it was announced that GraphQL will have a Technical Steering Committee (TSC) going forward. More on that coming soon.
 

From eb0a06ca7151eb4c6911144ba56931e7e0f01c95 Mon Sep 17 00:00:00 2001
From: carolstran <hello@workwithcarolyn.com>
Date: Mon, 21 Dec 2020 21:16:41 +0100
Subject: [PATCH 10/11] Update content based on Ivan's code review

---
 src/content/faq/General.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index d154bcf681..d061ddc417 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -154,7 +154,7 @@ You can read more about [how versioning works in GraphQL](/learn/best-practices/
 
 ## How can I document my GraphQL API?
 
-One of the benefits of GraphQL is that it's inherently self-documenting. This means that when you use an interactive tool like [GraphiQL](https://github.com/graphql/graphiql), you’re able to explore what data is exposed by your GraphQL API. This includes the [fields](/learn/queries/#fields), [types](/learn/schema/#type-system), and more. You can also add a [description field](https://spec.graphql.org/draft/#sec-Documentation) to provide supplementary notes about your endpoint. 
+One of the benefits of GraphQL is that it's inherently self-documenting. This means that when you use an interactive tool like [GraphiQL](https://github.com/graphql/graphiql), you’re able to explore what data is exposed by your GraphQL API. This includes the [fields](/learn/queries/#fields), [types](/learn/schema/#type-system), and more. You can also add a [description field](https://spec.graphql.org/draft/#sec-Documentation) to provide supplementary notes about your endpoint. This description field supports strings and Markdown.
 
 For many, this provides enough API reference documentation. But it doesn’t reduce the need for other forms of documentation. You'll likely still need to create guides that explain how the general concepts tie into your specific use case.
 
@@ -162,6 +162,8 @@ For many, this provides enough API reference documentation. But it doesn’t red
 
 The latest working draft release of the GraphQL specification can be found at [spec.graphql.org/draft](https://spec.graphql.org/draft/). Previous editions are also available at permalinks that match their [release tag](https://github.com/graphql/graphql-spec/releases).
 
+The entire process behind each release is open source. You can monitor specification proposals by following [pull requests in the graphql-spec repository](https://github.com/graphql/graphql-spec/pulls). You can also watch past GraphQL Working Group discussions various proposals on [YouTube](https://www.youtube.com/channel/UCERcwLeheOXp_u61jEXxHMA).
+
 ## How can I contribute to the GraphQL specification?
 
 GraphQL is still evolving and contributions are very welcome! The specification (including the [latest working draft](https://spec.graphql.org/)) is open source. [Contributor guidelines](https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md) are available on GitHub.
@@ -172,7 +174,7 @@ There are more ways to get involved with GraphQL beyond the specification though
 
 It's not on this website yet, but we're working on it. For now, the specification includes details for [how to write and execute subscriptions](https://spec.graphql.org/draft/#sec-Subscription). 
 
-If you'd like to help write guides on subscriptions, please [let us know](https://github.com/graphql/graphql.github.io/issues/new). 
+If you'd like to help write guides on subscriptions, please [let us know](https://github.com/graphql/graphql.github.io/issues/993). 
 
 ## Does GraphQL replace Redux or other state management libraries?
 

From 3269a66725ec99c1655527e45535c06edbd85654 Mon Sep 17 00:00:00 2001
From: Carolyn Stransky <hello@workwithcarolyn.com>
Date: Mon, 21 Dec 2020 21:18:06 +0100
Subject: [PATCH 11/11] Apply suggestions from Ivan's code review

Co-authored-by: Ivan Goncharov <ivan.goncharov.ua@gmail.com>
---
 src/content/faq/General.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/content/faq/General.md b/src/content/faq/General.md
index d061ddc417..ab91bc89da 100644
--- a/src/content/faq/General.md
+++ b/src/content/faq/General.md
@@ -66,7 +66,7 @@ While HTTP is the most common choice for client-server protocol, it’s not the
 
 ## How does GraphQL affect my product’s performance?
 
-With GraphQL, every field on every type has a focused, single-purpose function for resolving that value. Also, instead of trying to handle data parsing on the client, [GraphQL moves that logic to the server](/learn/best-practices/#server-side-batching-caching). As a result, there are some inherent performance benefits. Minimizing over-fetching and making [fewer roundtrips to the server](/learn/queries/#fields) are two of them.
+On a typical GraphQL backend, every field on every type has a focused, single-purpose function for resolving that value. Also, instead of trying to handle data batching on the client, [GraphQL moves that logic to the server](/learn/best-practices/#server-side-batching-caching). As a result, there are some inherent performance benefits. Minimizing over-fetching and making [fewer roundtrips to the server](/learn/queries/#fields) are two of them.
 
 Other performance factors should be considered when building out your GraphQL implementation. For example, it’s possible for a GraphQL service to be ‘chatty’ and repeatedly load data from your database. This is commonly solved by [implementing a batching technique](/learn/best-practices/#server-side-batching-caching) or [utilizing a tool like DataLoader](https://github.com/graphql/dataloader). 
 
@@ -108,7 +108,7 @@ You can find out more by visiting [foundation.graphql.org](https://foundation.gr
 
 ## Is GraphQL scalable?
 
-Yes, if you scale it. 
+Yes, GraphQL is designed to be scalable and is used by many companies in production under a very high load.
 
 GraphQL comes with some [built-in performance boosts](#how-does-graphql-affect-my-product-s-performance) that can help. But once you push it to production, you're responsible for scaling it across instances and monitoring performance.