Followup tweaks

docs/source/caching/cache-field-behavior.mdx

@@ -8,7 +8,9 @@ You can customize how a particular field in your Apollo Client cache is read and
 * A [`merge` function](#the-merge-function) that specifies what happens when field's cached value is written
 * An array of [key arguments](#specifying-key-arguments) that help the cache avoid storing unnecessary duplicate data.
 
-You provide field policies to the constructor of `InMemoryCache`. Each field policy is defined inside whichever [`TypePolicy` object](./cache-configuration/#typepolicy-fields)  corresponds to the field's parent type. The following example defines a field policy for the `name` field of a `Person` type:
+You provide field policies to the constructor of `InMemoryCache`. Each field policy is defined inside whichever [`TypePolicy` object](./cache-configuration/#typepolicy-fields)  corresponds to the field's parent type.
+
+The following example defines a field policy for the `name` field of a `Person` type:
 
 ```ts {5-10}
 const cache = new InMemoryCache({
@@ -48,9 +50,11 @@ const cache = new InMemoryCache({
     Person: {
       fields: {
         name: {
+          // highlight-start
           read(name = "UNKNOWN NAME") {
             return name;
           }
+          // highlight-end
         },
       },
     },

docs/source/caching/cache-interaction.mdx

@@ -63,7 +63,7 @@ If your cache contains data for _all_ of the query's fields, `readQuery` returns
 
 > Apollo Client automatically queries for every object's `__typename` by default, even if you don't include this field in your query string.
 
-**Do not modify the returned object directly.** The same object might be returned to multiple components. To update data in the cache, see [Combining reads and writes](#combining-reads-and-writes).
+**Do not modify the returned object directly.** The same object might be returned to multiple components. To update cached data safely, see [Combining reads and writes](#combining-reads-and-writes).
 
 If the cache is missing data for _any_ of the query's fields, `readQuery` returns `null`. It does _not_ attempt to fetch data from your GraphQL server.
 
@@ -192,6 +192,12 @@ client.writeFragment({
 
 All subscribers to the Apollo Client cache (including all active queries) see this change and update your application's UI accordingly.
 
+### `useFragment_experimental`
+
+> ⚠️ **The `useFragment_experimental` hook is currently at the [preview stage](https://www.apollographql.com/docs/resources/release-stages/#preview) in Apollo Client and is available by installing `@apollo/client@beta`.** If you have feedback on it, please let us know via [GitHub issues](https://github.com/apollographql/apollo-client/issues/new?assignees=&labels=&template=bug.md).
+
+You can read data for a given fragment directly from the cache using the `useFragment_experimental` hook. This hook returns an always-up-to-date view of whatever data the cache currently contains for a given fragment. [See the API reference.](../api/react/hooks-experimental)
+
 ## Combining reads and writes
 
 You can combine `readQuery` and `writeQuery` (or `readFragment` and `writeFragment`) to fetch currently cached data and make selective modifications to it. The following example creates a new `Todo` item and adds it to your cached to-do list. Remember, this addition is _not_ sent to your remote server.
@@ -269,12 +275,6 @@ The update function's return value is passed to either `writeQuery` or `writeFra
 
 > See the full API reference for [`cache.updateQuery`](../api/cache/InMemoryCache/#updatequery) and [`cache.updateFragment`](../api/cache/InMemoryCache/#updatefragment).
 
-### `useFragment_experimental`
-
-> ⚠️ **The `useFragment_experimental` hook is currently at the [preview stage](https://www.apollographql.com/docs/resources/release-stages/#preview) in Apollo Client and is available by installing `@apollo/client@beta`.** If you have feedback on it, please let us know via [GitHub issues](https://github.com/apollographql/apollo-client/issues/new?assignees=&labels=&template=bug.md).
-
-You can read data for a given fragment directly from the cache using the `useFragment_experimental` hook. This hook returns an always-up-to-date view of whatever data the cache currently contains for a given fragment. [See the API reference.](../api/react/hooks-experimental)
-
 ## Using `cache.modify`
 
 The `modify` method of `InMemoryCache` enables you to directly modify the values of individual cached fields, or even delete fields entirely.
@@ -283,7 +283,7 @@ The `modify` method of `InMemoryCache` enables you to directly modify the values
 * _Unlike_ `writeQuery` and `writeFragment`:
     * `modify` circumvents any [`merge` functions](cache-field-behavior/#the-merge-function) you've defined, which means that fields are always overwritten with exactly the values you specify.
     * `modify` _cannot_ write fields that do not already exist in the cache.
-* Watched queries can control what happens when they are invalidated by updates to the cache, by passing options like `fetchPolicy` and `nextFetchPolicy` to [`client.watchQuery`](../api/core/ApolloClient/#ApolloClient.watchQuery) or the [`useQuery`](../api/react/hooks/#options) hook.
+* Watched queries can control what happens when they're invalidated by updates to the cache, by passing options like `fetchPolicy` and `nextFetchPolicy` to [`client.watchQuery`](../api/core/ApolloClient/#ApolloClient.watchQuery) or the [`useQuery`](../api/react/hooks/#options) hook.
 
 ### Parameters
 

docs/source/caching/overview.mdx

@@ -5,24 +5,24 @@ description: Overview
 
 Apollo Client stores the results of your GraphQL queries in a local, [normalized](#data-normalization), in-memory cache. This enables Apollo Client to respond almost immediately to queries for already-cached data, without even sending a network request.
 
-For example, the _first_ time your app queries for a `Book` object with id `5`, the flow looks like this:
+For example, the _first_ time your app executes a `GetBook` query for a `Book` object with id `5`, the flow looks like this:
 
 ```mermaid
 sequenceDiagram
-  Apollo Client->>InMemoryCache: Queries for Book with id 5
-  Note over InMemoryCache: Book:5 not found in cache!
+  Apollo Client->>InMemoryCache: GetBook(bookId: "5")
+  Note over InMemoryCache: Book:5 not found<br/>in cache
   InMemoryCache->>GraphQL Server: Query sent to server
-  GraphQL Server->>InMemoryCache: Server responds with Book
+  GraphQL Server->>InMemoryCache: Server responds<br/>with Book
   Note over InMemoryCache: Book:5 is cached
   InMemoryCache->>Apollo Client: Returns Book
 ```
 
-And each _later_ time your app queries for that same object, the flow looks like this instead:
+And each _later_ time your app executes `GetBook` for that same object, the flow looks like this instead:
 
 ```mermaid
 sequenceDiagram
-  Apollo Client->>InMemoryCache: Queries for Book with id 5
-  Note over InMemoryCache: Book:5 found in cache!
+  Apollo Client->>InMemoryCache: GetBook(bookId: "5")
+  Note over InMemoryCache: Book:5 found<br/>in cache!
   InMemoryCache->>Apollo Client: Returns Book
   Note over GraphQL Server: (Server is never queried)
 ```
@@ -219,6 +219,6 @@ Our cache now contains five normalized objects (in addition to the `ROOT_QUERY`
 
 ## Next steps
 
-Now that you have a basic understanding of how Apollo Client's cache works, learn more about how to [install and configure it](./cache-configuration/).
+Now that you have a basic understanding of how Apollo Client's cache works, learn more about how to [configure it](./cache-configuration/).
 
 Then, you can learn how to [read and write data to your cache](./cache-interaction/) directly, without executing a query against your server. This is a powerful option for [local state management](../local-state/local-state-management/).