Improve v2 transition guide

Author: ryanashcraft

docs/transition-guides/v2.md

@@ -1,14 +1,16 @@
-# Important things to know
+# redux-query 1.x to 2.x Transition Guide
 
-## superagent has been updated to 3.x
+## Important things to know
+
+### superagent has been updated to 3.x
 
 Any code that relied on the older version may need to be updated.
 
-## Mutations have a subtly different behavior when updating entities
+### Mutations have a subtly different behavior when updating entities
 
 Motivation:
 
-With redux-query 1.x, if you have simultaneous mutations that update the same entity, you could end up in with one mutation completely overwriting the changes of the other one. This is because the entities state for the update is captured before the network request starts, as opposed to when it finishes. Naturally, this has confused several people and just feels wrong.
+With redux-query 1.x, if you have simultaneous mutations that update the same entity, you could end up in with one mutation completely overwriting the changes of the other one. This is because the entities state for the update is captured before the network request starts, as opposed to when it finishes.
 
 Solution:
 
@@ -19,7 +21,7 @@ Breaking changes:
 - Logic depending on the previous behavior will break and need to be updated.
 - The returned value to the promise on mutation failures no longer include the "entities" field.
 
-## New rollback behavior for optimistically-updated entities
+### New rollback behavior for optimistically-updated entities
 
 Motivation:
 
@@ -33,23 +35,23 @@ Additionally, we now offer a custom hook in query configs to enable manual contr
 
 See the README for more information on the `rollback` field.
 
-## New optional reducer for tracking failed query response data
+### New optional reducer for tracking failed query response data
 
 redux-query 2 exports a new reducer `errorsReducer` and accompanying set of selectors, `errorSelectors`. See the README for more information.
 
-# Other actions to take
+## Other actions to take
 
-## Update all references to `request` field in actions and queries state
+### Update all references to `request` field in actions and queries state
 
 The `request` fields in the start actions and stored in the queries reducer state has been removed in favor of a new field  called `networkHandler`.
 
 `networkHandler` is the returned value from the network interface, not the underlying superagent instance. When using redux-query in its default mode with the superagent network interface, you can get the superagent instance with `networkHandler.instance`.
 
-## Replace `removeEntity`/`REMOVE_ENTITY` and `removeEntities`/`REMOVE_ENTITIES` with `updateEntities`/`UPDATE_ENTITIES`
+### Replace `removeEntity` and `removeEntities` with `updateEntities`
 
 `REMOVE_ENTITY` and `REMOVE_ENTITIES` actions have been replaced with a more generic UPDATE_ENTITIES action.
 
-Example:
+For example, the following 1.x redux-query usage:
 
 ```javascript
 import { removeEntity } from 'redux-query';
@@ -68,11 +70,11 @@ dispatch(updateEntities({
 }));
 ```
 
-## Update all references to `reconcileQueryKey` and `getQueryKey`
+### Update all references to `reconcileQueryKey` and `getQueryKey`
 
 `reconcileQueryKey` and `getQueryKey` have been combined into a single function: `getQueryKey`. This function no longer accepts separate `url` and `body` parameters – instead you must pass a query config (or query-config-like object).
 
-Example:
+For example, the following 1.x redux-query usage:
 
 ```javascript
 import { getQueryKey } from 'redux-query';
@@ -86,14 +88,14 @@ import { getQueryKey } from 'redux-query';
 const queryKey = getQueryKey(query);
 ```
 
-## Update all references to `querySelectors`
+### Update all references to `querySelectors`
 
 All selectors in `querySelectors` have changed their signatures. The queries state is now the first argument, with a query config (or query-config-like object) as the second parameter.
 
-## Replace imports of `actions`, as it's no longer exported
+### Replace imports of `actions`, as it's no longer exported
 
 If you were importing `actions` from redux-query, you should change to import the actions directly. The only supported actions that are exported are: `cancelQuery`, `mutateAsync`, `requestAsync`, and `updateEntities`.
 
-## Rename "adapters" to "network interfaces"
+### Rename "adapters" to "network interfaces"
 
 This is not a breaking change, but if you use `queryMiddlewareAdvanced` – I recommend renaming any references to "adapters" to prevent future confusion.