Rework upsertQueryData descriptions

Author: markerikson

docs/rtk-query/usage/manual-cache-updates.mdx

@@ -12,57 +12,38 @@ description: 'RTK Query > Usage > Manual Cache Updates: Updating and creating ca
 
 ## Overview
 
-For most cases, in order to receive up to date data after a triggering a change in the backend,
-you can take advantage of `cache tag invalidation` to perform
-[automated re-fetching](./automated-refetching), which will cause a query to re-fetch its data
-when it has been told that a mutation has occurred which would cause its data to become out of date.
-In most cases, we recommend using `automated re-fetching` as a preference over `manual cache updates`,
-unless you encounter the need to do so.
+For most cases, in order to receive up to date data after a triggering a change in the backend, you can take advantage of cache tag invalidation to perform [automated re-fetching](./automated-refetching).  This will cause a query to re-fetch its data when it has been told that a mutation has occurred which would cause its data to become out of date.
 
-However, in some cases when refetch is not necessary, you may wish to update the cache data manually.
-You can do it using provided by created API `util` object methods for both:
+We recommend using automated re-fetching as a preference over manual cache updates in most situations.
 
-- updating already existing cache entries with [`updateQueryData`](../api/created-api/api-slice-utils.mdx#updatequerydata)
-- creating new or replacing existing cache entries with [`upsertQueryData`](../api/created-api/api-slice-utils.mdx#upsertquerydata)
+However, there _are_ use cases when manual cache updates are necessary, such as "optimistic" or "pessimistic" updates, or modifying data as part of cache entry lifecycles.
 
-Anywhere you have access to the `dispatch` method for the store instance, you can dispatch the
-result of calling `updateQueryData` in order to update the cache data for a query endpoint,
-if the corresponding cache entry exists or `upsertQueryData` to create new or replace existing one.
+RTK Query exports thunks for these use cases, attached to `api.utils`:
+
+- [`updateQueryData`](../api/created-api/api-slice-utils.mdx#updatequerydata): updates an already existing cache entry 
+- [`upsertQueryData`](../api/created-api/api-slice-utils.mdx#upsertquerydata): creates or replaces cache entries
+
+Since these are thunks, you can dispatch them anywhere you have access to `dispatch`.
 
 ### Updating existing cache entries
-For updates of existing cache entries use [`updateQueryData`](../api/created-api/api-slice-utils.mdx#updatequerydata).
 
-`updateQueryData` is strictly intended to perform _updates_ to existing cache entries,
-not create new entries. If an `updateQueryData` thunk action is dispatched that corresponds to
-no existing cache entry for the provided `endpointName` + `args` combination, the provided `recipe`
-will not be called, and no `patches` or `inversePatches` will be returned.
+For updates of existing cache entries, use [`updateQueryData`](../api/created-api/api-slice-utils.mdx#updatequerydata).
+
+`updateQueryData` is strictly intended to perform _updates_ to existing cache entries, not create new entries. If an `updateQueryData` thunk action is dispatched and the `endpointName` + `args` combination that does not match any existing cache entry, the provided `recipe` callback will not be called, and no `patches` or `inversePatches` will be returned.
 
 Use cases for manual update of cache entries:
 - Providing immediate feedback to the user when a mutation is attempted
-- After a mutation, updating a single item in a large list of items that is already cached,
-rather than re-fetching the whole list
-- Debouncing a large number of mutations with immediate feedback as though they are being
-applied, followed by a single request sent to the server to update the debounced attempts
+- After a mutation, updating a single item in a large list of items that is already cached, rather than re-fetching the whole list
+- Debouncing a large number of mutations with immediate feedback as though they are being applied, followed by a single request sent to the server to update the debounced attempts
 
 ### Creating new cache entries or replacing existing ones
-To create or replace existing cache entries use [`upsertQueryData`](../api/created-api/api-slice-utils.mdx#upsertquerydata).
 
-`upsertQueryData` is intended to perform _replacements_ to existing cache entries or _creation_ of new ones.
-Due to the fact, that in `upsertQueryData` we do not have access to the previous state of the cache entry, since it can not exist yet,
-the update may be performed only as a replacement. On the contrary, `updateQueryData` allows to perform a patching of the existing cache entry, but
-can not create a new one.
+To create or replace existing cache entries, use [`upsertQueryData`](../api/created-api/api-slice-utils.mdx#upsertquerydata).
 
-:::tip
-
-Manual creation of cache entries can introduce significant improvement in application performance and UX. Thanks to using the data we are already
-aware of, we can avoid unnecessary requests and loaders.
+`upsertQueryData` is intended to perform _replacements_ to existing cache entries or _creation_ of new ones. Since `upsertQueryData` does not have access to the previous state of the cache entry, the update may be performed only as a replacement. In comparison, `updateQueryData` allows patching of the existing cache entry, but cannot create a new one.
 
-:::
 
-Use cases for upserting cache entries in pair with [pessimistic updates](../usage/manual-cache-updates.mdx#pessimistic-updates):
-- you create a new Post and backend returns its complete data including `id`. Then we
-  can use `upsertQueryData` to create a new cache entry for the `getPostById(id)` query, preventing unnecessary fetching it on enter.
-- same can be applied for batch creations of items, when backend returns a list of created items with their ids.
+One example use case is [pessimistic updates](../usage/manual-cache-updates.mdx#pessimistic-updates).  If the client makes an API call to create a `Post`, the backend could return its complete data including the `id`. Then we can use `upsertQueryData` to create a new cache entry for the `getPostById(id)` query, preventing an extra fetch to retrieve the item later.
 
 ## Recipes