docs: improve @connection docs

docs/source/caching/advanced-topics.mdx

@@ -2,7 +2,7 @@
 title: Advanced topics on caching in Apollo Client
 ---
 
-This article describes special cases and considerations when using the Apollo Client cache.
+This article describes special cases and considerations when using the [Apollo Client cache](./overview).
 
 ## Bypassing the cache
 
@@ -22,7 +22,11 @@ You can persist and rehydrate the `InMemoryCache` from a storage provider like `
 
 To get started, pass your cache and a storage provider to `persistCache`. By default, the contents of your cache are immediately restored asynchronously, and they're persisted on every write to the cache with a short configurable debounce interval.
 
-> **Note:** The `persistCache` method is async and returns a `Promise`.
+<Note>
+
+The `persistCache` method is async and returns a `Promise`.
+
+</Note>
 
 ```js
 import AsyncStorage from '@react-native-async-storage/async-storage';
@@ -60,7 +64,7 @@ function Profile() {
 }
 ```
 
-> To reset the cache _without_ refetching active queries, use `client.clearStore()` instead of `client.resetStore()`.
+To reset the cache _without_ refetching active queries, use `client.clearStore()` instead of `client.resetStore()`.
 
 ### Responding to cache resets
 
@@ -97,7 +101,7 @@ function Foo (){
   const client = useApolloClient();
 
   useEffect(() => {
-    const unsubscribe = client.onResetStore(() => 
+    const unsubscribe = client.onResetStore(() =>
       new Promise(()=>setReset(reset + 1))
     );
 
@@ -174,7 +178,11 @@ In these cases, you can provide a `refetchQueries` option to the `useMutation` h
 
 For details, see [Refetching queries](../data/mutations/#refetching-queries).
 
-> Note that although `refetchQueries` can be faster to implement than an `update` function, it also requires additional network requests that are usually undesirable. For more information, see [this blog post](https://www.apollographql.com/blog/when-to-use-refetch-queries-in-apollo-client/).
+<Note>
+
+Although `refetchQueries` can be faster to implement than an `update` function, it also requires additional network requests that are usually undesirable. For more information, see [this blog post](https://www.apollographql.com/blog/when-to-use-refetch-queries-in-apollo-client/).
+
+</Note>
 
 ## Cache redirects
 
@@ -233,23 +241,63 @@ This `read` function uses the `toReference` helper utility to generate and retur
 
 Now whenever a query includes the `book` field, the `read` function above executes and returns a reference to a `Book` object. Apollo Client uses this reference to look up the object in its cache and return it if it's present. If it _isn't_ present, Apollo Client knows it needs to execute the query over the network.
 
-> ⚠️ **Note:** To avoid a network request, _all_ of a query's requested fields must already be present in the cache. If the detail view's query fetches _any_ `Book` field that the list view's query _didn't_, Apollo Client considers the cache hit to be incomplete, and it executes the full query over the network.
+<Note>
+
+To avoid a network request, _all_ of a query's requested fields must already be present in the cache. If the detail view's query fetches _any_ `Book` field that the list view's query _didn't_, Apollo Client considers the cache hit to be incomplete, and it executes the full query over the network.
+
+</Note>
 
 ## Pagination utilities
 
+Pagination is a best practice in GraphQL [for several reasons](../pagination/overview). Apollo Client enables fetching and caching paginated results using the [Core pagination API](../pagination/core-api). The API includes a few important utilities, including the [`fetchMore`](../pagination/core-api/#the-fetchmore-function) function and the `@connection` directive.
+
 ### Incremental loading: `fetchMore`
 
-You can use the `fetchMore` function to update a query's cached result with data returned by a _followup_ query. Most often, `fetchMore` is used to handle infinite-scroll pagination and other situations where you're loading _more_ data when you already have _some_.
+You can use the `fetchMore` function to update a query's cached result with data returned by a _follow-up_ query. Most often, `fetchMore` is used to handle infinite-scroll pagination and other situations where you're loading more data when you already have some.
 
 For details, see [The `fetchMore` function](../pagination/core-api/#the-fetchmore-function).
 
 ### The `@connection` directive
 
-Fundamentally, paginated queries are the same as any other query with the exception that calls to `fetchMore` update the same cache key. Because these queries are cached by both the initial query and their parameters, a problem arises when later retrieving or updating paginated queries in the cache. We don't care about pagination arguments such as limits, offsets, or cursors outside of the need to `fetchMore`, nor do we want to provide them simply for accessing cached data.
+The `@connection` directive solves the problem of multiple distinct copies of the same field in the cache. This can happen with paginated queries because the `fetchMore` function sends follow-up queries to fetch additional pages of results using arguments like [`offset`](../pagination/offset-based/) and [`limit`](../pagination/offset-based/). These arguments inadvertently fragment data from different pagination requests across the cache.
+
+The `@connection` directive lets you unify paginated results by specifying a custom, stable cache key for a field. It also lets you set filters to specify which arguments should create separate stores in the cache.
+
+<Tip>
 
-To solve this, you can use the `@connection` directive to specify a custom cache key for results. A connection allows us to set the cache key for a field and to filter which arguments actually alter the query.
+Starting in Apollo Client v3, setting the [`keyArgs` field policy](../pagination/key-args/#setting-keyargs) is the most straightforward way to resolve fragmented pagination results in the cache. For example, setting [`keyArgs` to `false`](../pagination/key-args/#supported-values-for-keyargs) indicates that no arguments should be included in cache keys, causing all pagination results to be cached together. Additionally, you only have to set your `keyArgs` configuration once, rather than using `@connection` in multiple queries.
 
-To use the `@connection` directive, add it to the segment of the query you want a custom store key for and provide the `key` parameter to specify the store key. In addition to the `key` parameter, you can also include the optional `filter` parameter, which takes an array of query argument names to include in the generated custom store key.
+For example, you can use the following [`keyArgs`](../pagination/key-args/#setting-keyargs) configuration for the same effect as the [`@connection` directive usage](#connection-directive-usage) described below.
+
+```js
+const cache = new InMemoryCache({
+  typePolicies: {
+    Query: {
+      fields: {
+        feed: {
+          keyArgs: ["type"]
+        }
+      }
+    }
+  }
+})
+```
+
+With this centralized `keyArg`s configuration, you don't need to include the `@connection` directive in your queries because the `type` argument is adequate for keeping feeds of different types separate in the cache.
+
+The `@connection` directive is useful when you want to store distinct data in the cache on a _query-by-query_, _field-by-field_ basis. See the [advanced usage instructions](#advanced-connection-directive-usage) below for more details.
+
+</Tip>
+
+#### `@connection` directive usage
+
+<Tip>
+
+For the standard `@connection` directive usage described in this section, it's best to configure a [`keyArgs` field policy](../pagination/key-args/#setting-keyargs) as described [above](#the-connection-directive). For an example of storing distinct data on a _query-by-query_ basis, see the [advanced usage instructions](#advanced-connection-directive-usage).
+
+</Tip>
+
+To use the `@connection` directive, add it to the field you want a custom cache key for. The directive requires a `key` parameter to specify the custom cache key. You can optionally include the `filter` parameter, which takes an array of query argument names to include in the generated custom cache key.
 
 ```js
 const query = gql`
@@ -261,9 +309,9 @@ const query = gql`
 `
 ```
 
-With the above query, even with multiple `fetchMore`s, the results of each feed update will always result in the `feed` key in the store being updated with the latest accumulated values. In this example, we also use the `@connection` directive's optional `filter` argument to include the `type` query argument in the store key, which results in multiple store values that accumulate queries from each type of feed.
+With the above query, even when multiple `fetchMore`s queries are performed, each feed update always results in an update to the cache's `feed` key with the latest accumulated values. The example also uses the `@connection` directive's optional `filter` argument to include the `type` query argument in the cache key. This creates multiple cache values that accumulate queries from each type of feed.
 
-Now that we have a stable store key, we can easily use `writeQuery` to perform a store update, in this case clearing out the feed.
+With a stable cache key, you can use [`writeQuery`](./cache-interaction/#writequery) to perform a cache update that clears out the feed.
 
 ```js
 client.writeQuery({
@@ -283,4 +331,34 @@ client.writeQuery({
 });
 ```
 
-Note that because we are only using the `type` argument in the store key, we don't have to provide `offset` or `limit`.
+<Note>
+
+Because this example uses the `type` argument in the cache key, it doesn't need to provide `offset` or `limit` arguments.
+
+</Note>
+
+#### Advanced `@connection` directive usage
+
+The `@connection` directive is useful when using the same field in multiple queries, with no distinguishing arguments (for example, `type`)  that `keyArgs` can use, and you want to keep that field's data separate in the cache.
+
+In the example below, the `@connection` key ensures that `feed` data from `ArticlesFeed` query is stored in the `article-feed` cache key and data from `ProductsFeed` in the `product-feed` cache key.
+
+```js
+const ArticlesFeed = gql`
+  query ArticlesFeed($offset: Int, $limit: Int) {
+    feed(offset: $offset, limit: $limit) @connection(key: "article-feed") {
+      ...FeedEntry
+    }
+  }
+`
+```
+
+```js
+const ProductsFeed = gql`
+  query ProductsFeed($offset: Int, $limit: Int) {
+    feed(offset: $offset, limit: $limit) @connection(key: "product-feed") {
+      ...FeedEntry
+    }
+  }
+`
+```