Apply suggestions from code review

Co-authored-by: Benjie <[email protected]>

Author: mandiwise

src/pages/learn/execution.mdx

@@ -53,7 +53,7 @@ If a field produces a scalar value like a string or number, then the execution c
 
 ## Root fields and resolvers
 
-At the top level of every GraphQL server is an Object type that represents the possible entry points into the GraphQL API, it's often called the `query` root operation type or the `Query` type. If the API supports mutations to write data and subscriptions to fetch real-time data as well, then it will have `Mutation` and `Subscription` types that expose fields to perform these kinds of operations too. You can learn more about these types on the [Schema and Types page](/learn/schema/#the-query-mutation-and-subscription-types).
+At the top level of every GraphQL server is an Object type that represents the possible entry points into the GraphQL API, it's often called "the `query` root operation type" or the `Query` type. If the API supports mutations to write data and subscriptions to fetch real-time data as well, then it will have `Mutation` and `Subscription` types that expose fields to perform these kinds of operations too. You can learn more about these types on the [Schema and Types page](/learn/schema/#the-query-mutation-and-subscription-types).
 
 In this example, our `Query` type provides a field called `human` which accepts the argument `id`. The resolver function for this field likely accesses a database and then constructs and returns a `Human` type:
 
@@ -65,12 +65,12 @@ function Query_human(obj, args, context, info) {
 }
 ```
 
-This example is written in JavaScript, however, GraphQL servers can be built in [many different languages](/code/). The resolver function receives four arguments:
+This example is written in JavaScript, however GraphQL servers can be built in [many different languages](/code/). In the reference implementation, a resolver function receives four arguments:
 
 - `obj`: The previous object (for a field on the root `Query` type, this argument is often not used).
 - `args`: The arguments provided to the field in the GraphQL operation.
 - `context`: A value provided to every resolver that may hold important contextual information like the currently logged in user, or access to a database.
-- `info`: A value holding field-specific information relevant to the current operation as well as the schema details. Refer to [type GraphQLResolveInfo for more details](/graphql-js/type/#graphqlobjecttype).
+- `info`: generally only used in advanced use-cases, this is a value holding field-specific information relevant to the current operation as well as the schema details; refer to [type GraphQLResolveInfo](/graphql-js/type/#graphqlobjecttype) for more details.
 
 <Callout type="info">
 Note that while a query operation could technically write data to the underlying data system during its execution, mutation operations are conventionally used for requests that produce side effects during their execution. And because mutation operations produce side effects, GraphQL implementations can be expected to execute these fields serially.
@@ -88,7 +88,7 @@ function Query_human(obj, args, context, info) {
 }
 ```
 
-The `context` is used to provide access to a database. Specifically, the `id` argument in the GraphQL query is used to fetch data for a user. Since loading from a database is an asynchronous operation, this returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). In JavaScript, Promises are used to work with asynchronous values, but the same concept exists in many languages, often called _Futures_, _Tasks_, or _Deferred_. When the database returns the data, we can construct and return a new `Human` object.
+The `id` argument in the GraphQL query specifies the user whose data is requested, while `context` provides access to retrieve this data from a database. Since loading from a database is an asynchronous operation, this returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). In JavaScript, Promises are used to work with asynchronous values, but the same concept exists in many languages, often called _Futures_, _Tasks_, or _Deferred_. When the database returns the data, we can construct and return a new `Human` object.
 
 Notice that while the resolver function needs to be aware of Promises, the GraphQL query does not. It simply expects the `human` field to return something that can be further resolved to a scalar `name` value. During execution, GraphQL will wait for Promises, Futures, and Tasks to be completed before continuing and will do so with optimal concurrency.
 
@@ -102,11 +102,11 @@ function Human_name(obj, args, context, info) {
 }
 ```
 
-A GraphQL server is powered by a type system that is used to determine what to do next. Even before the `human` field returns anything, GraphQL knows that the next step will be to resolve fields on the `Human` type since the type system tells it that the `human` field will return this output type.
+A GraphQL server is powered by a type system that is used to determine what to do next. Even before the `human` field returns anything, GraphQL knows the next step will be to resolve fields on the `Human` type since the type system tells it that the `human` field will return this output type.
 
 Resolving the name in this case is straightforward. The name resolver function is called and the `obj` argument is the new `Human` object returned from the previous field. In this case, we expect this object to have a `name` property, which we can read and return directly.
 
-Many GraphQL libraries will let you omit resolvers this simple and will assume that if a resolver isn't provided for a field, a property of the same name should be read and returned.
+Many GraphQL libraries let you omit resolvers this simple, assuming that if a resolver isn't provided for a field, a property of the same name should be read and returned.
 
 ## Scalar coercion
 
@@ -168,7 +168,7 @@ As we can see, each field in the nested selection sets resolves to a scalar leaf
 To recap what we've learned about execution:
 
 - Each field in a GraphQL type system will have a corresponding resolver function that provides data for the field from an existing data source
-- Execution begins at the top-level `query`, `mutation`, and `subscription` fields
+- Execution begins at the top-level `Query`, `Mutation`, or `Subscription` fields
 - Resolvers may execute asynchronously
 - Scalar coercion converts values into the types expected by the schema
 - When a field on an Object type returns a List type of other objects, additional data may need to be fetched from the underlying data source to transform any foreign key-like references (such as IDs) into the related objects

src/pages/learn/response.mdx

@@ -27,10 +27,10 @@ The inclusion of the `data` key isn't an arbitrary decision made by the underlyi
 
 One thing that the GraphQL specification doesn't require is a specific serialization format for the response. That said, responses are typically formatted as JSON, as in the example above.
 
-Additionally, the GraphQL specification doesn't require the use of a particular transport protocol for requests either, although it is [common for HTTP to be used](/learn/serving-over-http/) with `POST` or `GET` methods for stateless query and mutations operations. Long-lived, stateful subscription operations are often supported by WebSockets or server-sent events instead.
+Additionally, the GraphQL specification doesn't require the use of a particular transport protocol for requests either, although it is [common for HTTP to be used](/learn/serving-over-http/) for stateless query and mutations operations. Long-lived, stateful subscription operations are often supported by WebSockets or server-sent events instead.
 
 <Callout type="info">
-There is [a draft GraphQL over HTTP specification](https://github.com/graphql/graphql-over-http/blob/main/spec/GraphQLOverHTTP.md) available with further guidelines for using HTTP with a GraphQL clients and servers.
+There is [a draft GraphQL over HTTP specification](https://graphql.github.io/graphql-over-http/draft/) available with further guidelines for using HTTP with GraphQL clients and servers.
 </Callout>
 
 ## Errors
@@ -51,7 +51,7 @@ operation {
 }
 ```
 
-The `message` key inside the `errors` object provides some helpful information for the developer to understand what kind of error was raised, and the `locations` key indicates where the error occurred in the document.
+The `message` key inside the `errors` object provides some helpful information for the developer to understand what kind of error was raised, and the `locations` key, if present, indicates where the error occurred in the document.
 
 Sometimes, a GraphQL request may be syntactically correct, but when the server parses and [validates](/learn/validation/) the document against the schema, it finds an issue with part of the operation and raises a _validation error_.
 
@@ -81,9 +81,9 @@ In the previous examples, we can see that when a request error occurs the `data`
 
 ### Field errors
 
-Field errors are raised if something unexpected happens when a resolver function is called. For example, a resolver may provide a null value for a field that has a Non-Null output type or there may be some other internal server error during execution.
+Field errors are raised if something unexpected happens during execution. For example, a resolver may raise an error directly, or may return invalid data such as a null value for a field that has a Non-Null output type.
 
-In these cases, the `data` key will be included in the result with the `errors` key because GraphQL will try to continue execution beyond the problematic field and potentially return a partial result.
+In these cases, GraphQL will attempt to continue executing the other fields and return a partial response, with the `data` key appearing alongside the `errors` key.
 
 Let's look at an example:
 
@@ -103,18 +103,19 @@ As with network calls to any type of API, network errors that are not specific t
 
 ## Extensions
 
-The final top-level key allowed by the GraphQL specification in a response is the `extentions` key. This key is reserved for GraphQL implementations to provide additional information about the response and there are no restrictions on what it may contain. 
+The final top-level key allowed by the GraphQL specification in a response is the `extentions` key. This key is reserved for GraphQL implementations to provide additional information about the response and though it must be an object if present, there are no other restrictions on what it may contain.
 
-For example, some GraphQL servers may include telemetry data or information about rate limit consumption under this key. Note that what data are available in `extensions` and whether this data is available in production or development environments will depend entirely on the specific GraphQL implementation.
+For example, some GraphQL servers may include telemetry data or information about rate limit consumption under this key. Note that what data is available in `extensions` and whether this data is available in production or development environments will depend entirely on the specific GraphQL implementation.
 
 ## Next steps
 
 To recap what we've learned about GraphQL response formats:
 
 - The GraphQL specification allows three top-level keys in a response: `data`, `errors`, and `extensions`
+- At least one of `data` or `errors` will be present on the response (when it contains both it is a "partial response")
 - The `data` key contains the result of the executed operation
 - Information about raised errors is included in the `errors` key of the response
-- Request errors (such as syntax or validation errors) are raised before execution begins so there won't be any data included in the response
+- Request errors (such as syntax or validation errors) are raised before execution begins so `data` won't be included in the response
 - When a field error occurs during execution, there will be a description of the issue in the `errors` key and there may be partial data included with the `data` key
 - GraphQL implementations may include additional arbitrary information about the response in the `extensions` key