Apply suggestions from code review

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

Author: mandiwise

src/pages/learn/mutations.mdx

@@ -39,7 +39,7 @@ type Mutation {
 
 Like queries, mutation fields are added to one of the [root operation types](https://spec.graphql.org/draft/#sec-Root-Operation-Types) that provide an entry point to the API. In this case, we define the `createReview` field on the `Mutation` type. 
 
-Mutation fields can also accept arguments and you might notice that the `review` argument has an input type set to `ReviewInput`. This is known as [Input Object type](/learn/schema/#input-object-types), which allows us to pass in a whole object to be created instead of individual scalar values only.
+Mutation fields can also accept arguments and you might notice that the `review` argument has an input type set to `ReviewInput`. This is known as [Input Object type](/learn/schema/#input-object-types), which allows us to pass in a structured object containing information the mutation can use instead of individual scalar values only.
 
 Also like just like queries, if the mutation field returns an Object type, then you specify a selection set of its fields in the operation:
 
@@ -53,7 +53,7 @@ mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
 }
 ```
 
-While the `createReview` field could be defined with any valid output type in the schema, it's conventional to specify an output type that corresponds to whatever is modified during the mutation—in this case, the `Review` type. This can be useful for clients that need to fetch the new state of an object after an update.
+While the `createReview` field could be defined with any valid output type in the schema, it's conventional to specify an output type that relates to whatever is modified during the mutation—in this case, the `Review` type. This can be useful for clients that need to fetch the new state of an object after an update.
 
 Recall that GraphQL is meant to work with your existing code and data, so the actual creation of the review is up to you when clients send this operation to the GraphQL server. A hypothetical function that writes the new review to a database during a `createReview` mutation might look like this:
 
@@ -67,7 +67,7 @@ Mutation: {
 }
 ```
 
-You can learn more about GraphQL provides data for fields on the [Execution page](/learn/execution).
+You can learn more about how GraphQL provides data for fields on the [Execution page](/learn/execution).
 
 ## Update existing data
 
@@ -91,7 +91,7 @@ mutation UpdateHumanName($id: ID!, $name: String!) {
 }
 ```
 
-This example demonstrates an important distinction from REST. To update a human's properties using a REST API, you would likely send any updated data to a generalized endpoint for that resource using a `PATCH` request. With GraphQL, instead of simply creating an `updateHuman` mutation, you can define more specific mutation fields such as `updateHumanName`that are designed for the task at hand.
+This example demonstrates an important distinction from REST. To update a human's properties using a REST API, you would likely send any updated data to a generalized endpoint for that resource using a `PATCH` request. With GraphQL, instead of creating a generic `updateHuman` mutation, you may choose to define more specific mutation fields such as `updateHumanName` that are designed for the task at hand.
 
 Purpose-built mutation fields can help make a schema more expressive by allowing the input types for field arguments to be Non-Null types (a generic `updateHuman` mutation would likely need to accept many nullable arguments to handle different update scenarios). Defining this requirement in the schema also eliminates the need for other runtime logic to determine that the appropriate values were submitted to perform the client's desired write operation.
 

src/pages/learn/subscriptions.mdx

@@ -4,7 +4,7 @@ import { Callout } from "nextra/components"
 
 <p className="learn-subtitle">Learn how to get real-time updates from a GraphQL server</p>
 
-In addition to reading and writing data using stateless query and mutation operations, the GraphQL specification also describes how to fetch data in real-time via long-lived requests. On this page, we'll explore how clients can receive updated data in response to some event on a GraphQL server using subscription operations.
+In addition to reading and writing data using stateless query and mutation operations, the GraphQL specification also describes how to receive real-time updates via long-lived requests. On this page, we'll explore how clients can subscribe to details of events on a GraphQL server using subscription operations.
 
 <Callout type="info">
 Many of the features of GraphQL operations that apply to queries also apply to subscriptions, so review the [Queries](/learn/queries/) page first before proceeding.
@@ -36,7 +36,7 @@ GraphQL subscriptions are typically backed by a separate pub/sub system so that
 For the previous example, we could imagine publishing a `REVIEW_CREATED` message to a pub/sub system when a client submits a new review with the `createReview` mutation, and then listening for this event in the resolver function for the `reviewCreated` subscription field so that the server may send this data to subscribed clients.
 
 <Callout type="info">
-Note that subscriptions are different from the concept of _live queries_, which are not formally described in the specification and are often implemented differently in GraphQL various implementations using an `@live` executable directive. [Read more about the ongoing discussion on a formal specification for live queries here.](https://github.com/graphql/graphql-spec/issues/386)
+Note that subscriptions are different from the concept of _live queries_, a loosely defined feature that some GraphQL implementations may offer. [Read more about the ongoing discussion on a formal specification for live queries here.](https://github.com/graphql/graphql-spec/issues/386)
 </Callout>
 
 As with query and mutation operations, GraphQL doesn't specify what transport protocol to use, so it's up to the server to decide. In practice, you will often see them implemented with WebSockets or server-sent events. Clients that want to send subscription operations will also need to support the chosen protocol. There are community-maintained specifications for implementing GraphQL subscriptions with [WebSockets](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md) and [server-sent events](https://github.com/enisdenjo/graphql-sse/blob/master/PROTOCOL.md).
@@ -60,7 +60,7 @@ subscription {
 }
 ```
 
-But this operation would run:
+But this document is valid:
 
 ```graphql
 subscription NewReviewCreated {
@@ -79,7 +79,7 @@ subscription FriendListUpdated($id: ID!) {
 }
 ```
 
-As with query and mutation operations, the document above contains multiple subscription operations so each operation must be named.
+As with query and mutation operations, the document above contains multiple operations so each operation must be named, and the name of the operation to execute must be specified in the request.
 
 ## Using subscriptions at scale
 
@@ -89,7 +89,7 @@ Similarly, client libraries will typically need more advanced features to handle
 
 In practice, a GraphQL API that supports subscriptions will call for a more complicated architecture than one that only exposes query and mutation fields. How this architecture is designed will depend on the specific GraphQL implementation, what pub/sub system supports the subscriptions, and the chosen transport protocol, as well as other requirements related to availability, scalability, and security of the real-time data.
 
-Subscription operations are best suited for data that changes often and incrementally, and for clients that need to receive those incremental updates as close to real-time as possible to deliver the expected user experience. For less frequent updates, periodic polling, mobile push notifications, or re-fetching queries based on user interaction may be the better solutions for keeping a client UI up to date.
+Subscription operations are well suited for data that changes often and incrementally, and for clients that need to receive those incremental updates as close to real-time as possible to deliver the expected user experience. For data with less frequent updates, periodic polling, mobile push notifications, or re-fetching queries based on user interaction may be the better solutions for keeping a client UI up to date.
 
 ## Next steps