[next-0.10] Add migration guide for v1.0

doc/book/working-documents/migration-1.md

@@ -17,7 +17,7 @@ You might also want to read our [general documentation on upgrading Garage](@/do
 The following are **breaking changes** in Garage v1.0 that require your attention when migrating:
 
 - The Sled metadata db engine has been **removed**. If your cluster was still
-  using sled, you will need to **use a Garage v0.9.x binary** to convert the
+  using Sled, you will need to **use a Garage v0.9.x binary** to convert the
   database using the `garage convert-db` subcommand. See
   [here](@/documentation/reference-manual/configuration/#db_engine) for the
   details of the procedure.
@@ -40,9 +40,10 @@ by restarting all nodes at once in the new version.
 
 The migration steps are as follows:
 
-1. Do `garage repair --all-nodes --yes tables` and `garage repair --all-nodes --yes blocks`,
+1. Do a `garage repair --all-nodes --yes tables`, check the logs and check that
-   check the logs and check that all data seems to be synced correctly between
+   all data seems to be synced correctly between nodes. If you have time, do
-   nodes. If you have time, do additional checks (`versions`, `block_refs`, etc.)
+   additional `garage repair` procedures (`blocks`, `versions`, `block_refs`,
+   etc.)
     
 2. Ensure you have a snapshot of your Garage installation that you can restore
    to in case the upgrade goes wrong:
@@ -67,8 +68,10 @@ The migration steps are as follows:
 
 3. Prepare your updated binaries and configuration files for Garage v1.0
 
-4. Shut down all v0.9 nodes simultaneously, and restart them all simultaneously in v1.0.
+4. Shut down all v0.9 nodes simultaneously, and restart them all simultaneously
-   Use your favorite deployment tool (Ansible, Kubernetes, Nomad) to achieve this as fast as possible.
+   in v1.0.  Use your favorite deployment tool (Ansible, Kubernetes, Nomad) to
-   Garage v1.0 should be in a working state as soon as enough nodes have started.
+   achieve this as fast as possible.  Garage v1.0 should be in a working state
+   as soon as enough nodes have started.
 
-5. Proceed with repair and monitoring as described in steps 10-12 above.
+5. Monitor your cluster in the following hours to see if it works well under
+   your production load.