Improve the docs

mattlord · mattlord · commit db8e9a8c7fe0 · 2023-08-11T11:37:40.000-04:00
Signed-off-by: Matt Lord &lt;mattalord@gmail.com&gt;
diff --git a/content/en/docs/18.0/reference/vreplication/movetables.md b/content/en/docs/18.0/reference/vreplication/movetables.md
@@ -203,10 +203,31 @@ If moving all tables, specifies tables to be skipped.
 
 <div class="cmd">
 
-When switching write (primary tablet) traffic for tables that are being moved from an unsharded keyspace to a sharded one, initialize any sequences being used by those tables on the target. They are initialized using the current maximum value for the column used on the target. This ensures that the sequence values on the target are greater than the maximum value seen on the source and ensure seamless auto generated primary key values when going from [MySQL auto_increment](https://dev.mysql.com/doc/refman/en/example-auto-increment.html) columns on the unsharded source to [Vitess Sequences](../../features/vitess-sequences/) on the sharded target.
+If specified, when switching write (primary tablet) traffic for tables that are being moved from an unsharded keyspace to a
+sharded one, initialize any sequences being used by those tables on the target. They are initialized using the current
+maximum value for the column across all shards on the target.
 
 </div>
 
+###### Uses
+
+* It's common that users import unsharded data into Vitess — sharding it in the process — or move
+tables from an unsharded keyspace to a sharded one as they become too large for a single MySQL instance.
+When doing either of these you would typically be leveraging [MySQL auto_increment](https://dev.mysql.com/doc/refman/en/example-auto-increment.html)
+columns for primary keys on the unsharded tables (source). On the sharded target, however, you will then
+need to use [Vitess Sequences](../../features/vitess-sequences/) in order to ensure that you continue having
+automatically generated incrementing unique primary keys _across all shards_. When it comes to [switching the write traffic](#switchtraffic)
+during this move you would need to manually ensure that you [initialize the sequences](../../features/vitess-sequences/#initializing-a-sequence)
+so that the next values they provide are higher than any already used on the source (with ample buffer in between
+to avoid potential identifier reuse and duplicate key errors immediately following the cutover). This flag tells Vitess
+to manage this sequence initialization for you as part of the `SwitchTraffic` operation to ensure a seamless cutover
+without any additional manual steps. For more information, please see [the feature request](https://github.com/vitessio/vitess/issues/13685).
+
+{{< info >}}
+You will still need to take the manual step of [creating each backing sequence table](../../features/vitess-sequences/#creating-a-sequence)
+in an unsharded keyspace of your choosing prior to the `SwitchTraffic` operation.
+{{< /info>}}
+
 #### --keep_data
 **optional**\
 **default** false
