Next 20 suggestions from code review

Co-authored-by: Devon Campbell <[email protected]>

docs/guides/migrations/guide.rst

@@ -646,9 +646,9 @@ Fixups during a squash
 If your schema doesn't match the schema in the database, EdgeDB will 
 prompt you to create a *fixup* file, which can be useful to, as the CLI 
 says, "automate upgrading other instances to a squashed revision". 
-You'll see fixups inside a folder called ``/fixups``. Their file names 
-are extremely long, but are simply two migration hashes joined together 
-by a dash. So a fixup that begins with
+You'll see fixups inside ``/dbschema/fixups``. Their file names 
+are extremely long because they are simply two migration hashes joined together 
+by a dash. This means a fixup that begins with
 
 .. code-block::
 
@@ -660,9 +660,7 @@ will have a file name a full 116 characters in length.
 
 The CLI output when using squash along with a fixup is pretty informative 
 on its own, so let's just walk through the output as you'll see it 
-in practice.
-
-First we'll begin with this schema:
+in practice. First we'll begin with this schema:
 
 .. code-block:: sdl
 
@@ -674,7 +672,7 @@ Then remove ``name: str;`` from the ``User`` type, migrate, put it
 back again, and migrate. You'll now have multiple files in your
 ``/migrations`` folder and will now be able to squash them.
 
-Then change to this schema without migrating it:
+Then change to this schema **without migrating it**:
 
 .. code-block:: sdl
 
@@ -683,7 +681,7 @@ Then change to this schema without migrating it:
     nickname: str;
   }
 
-Upon using ``edgedb migration create --squash``, the output is first 
+Now run ``edgedb migration create --squash``. The output is first 
 the same as with our previous squash:
 
 .. code-block:: bash
@@ -722,7 +720,7 @@ differs from what you have and offers to make a fixup file:
     Create a fixup file? [y/n]
     > y
 
-You will then see the the same questions that otherwise show up in 
+You will then see the the same questions that would otherwise show up in 
 a standard migration:
 
 .. code-block::
@@ -744,6 +742,10 @@ working with git after doing a squash with a fixup.
     The normal migration process will update your migration history:
         edgedb migrate
 
+We'll take its suggestion to apply the migration:
+
+.. code-block:: bash
+
     $ edgedb migrate
     
     Applied m1v3vqmwif4ml3ucbzi555mjgm4myxs2husqemopo2sz2m7otr22ka 
@@ -753,15 +755,15 @@ working with git after doing a squash with a fixup.
 
 .. note::
 
-    Squashing is still limited to schema changes, so queries inside 
+    Squashing is limited to schema changes, so queries inside 
     data migrations will be discarded during a squash.
 
 EdgeDB Watch
 ============
 
 Another option when quickly iterating over schema changes is ``edgedb watch``.
 This will create a long-running process that keeps track of every time you
-save as ``.esdl`` file inside your ``/migrations`` folder, letting you know
+save an ``.esdl`` file inside your ``/migrations`` folder, letting you know
 if your changes have successfully compiled or not. The command itself will
 lead to the following input ``edgedb watch`` starts up:
 
@@ -830,16 +832,16 @@ can't be resolved:
     Schema migration error:
     cannot proceed until .esdl files are fixed
 
-Once you correct the ``i32`` property to ``int32``, EdgeDB Watch will 
-let you know that things are okay now, and will become quiet again:
+Once you correct the ``i32`` type to ``int32``, EdgeDB Watch will 
+let you know that things are okay now and will resume quietly watching your schema and applying migrations:
 
 .. code-block::
 
     Resolved. Schema is up to date now.
 
-EdgeDB Watch is best run in a separate tab on your command line so 
-that you can take care of other tasks—including officially migrating 
-when you are satisfied with your current schema—without having to 
+EdgeDB Watch is best run in a separate instance of your command line so 
+that you can take care of other tasks — including officially migrating 
+when you are satisfied with your current schema — without having to 
 stop the process.
 
 If you are curious what is happening as EdgeDB Watch does its thing, 
@@ -856,18 +858,20 @@ Some migrations will contain nothing in their ``generated_by`` property,
 while those generated by EdgeDB Watch will have a 
 ``MigrationGeneratedBy.DevMode``. 
 
-(The final option for ``generated_by`` is
-``MigrationGeneratedBy.DDLStatement``, which will show up if you directly
-change your schema by using DDL - which is generally not recommended)
+.. note::
+
+    The final option (aside from ``DevMode`` and the empty set) for ``generated_by`` is
+    ``MigrationGeneratedBy.DDLStatement``, which will show up if you directly
+    change your schema by using DDL, which is generally not recommended.
 
 Once you are satisfied with your changes while running EdgeDB Watch, 
 just create the migration with ``edgedb migration create`` and then 
-apply them with one small change: ``edgedb migrate --dev-mode`` to 
+apply them with one small tweak to the ``migrate`` command: ``edgedb migrate --dev-mode`` to 
 let the CLI know to apply the migrations made during dev mode that 
 were made by EdgeDB Watch.
 
-So you really want to use DDL
-=============================
+So, you really want to use DDL?
+===============================
 
 You might have a good reason to use a direct DDL statement or two 
 to change your schema. How do you make that happen? EdgeDB disables 
@@ -889,7 +893,7 @@ the usage of DDL by default, so this attempt to use DDL will not work:
     migration flow.
 
 This configuration can be overridden by the following command which 
-changes the enum ``allow_bare_ddl``from the default ``NeverAllow`` 
+changes the enum ``allow_bare_ddl`` from the default ``NeverAllow`` 
 to the other option, ``AlwaysAllow``.
 
 .. code-block:: edgeql-repl
@@ -900,8 +904,8 @@ Note that the command is ``configure current database`` and not ``configure
 instance``, as ``allow_bare_ddl`` is evaluated on the database level.
 
 That wasn't so bad, so why did the CLI tell us to try to "avoid accidental 
-schema changes outside of the migration flow"? Why is DDL disabled 
-by default in the first place?
+schema changes outside of the migration flow?" Why is DDL disabled 
+after running a migration in the first place?
 
 So you really wanted to use DDL but now regret it
 =================================================