diff --git a/docs/graphql/core/migrations/upgrade-v3.rst b/docs/graphql/core/migrations/upgrade-v3.rst
index 8e4258b5e8f..0fedb13ead4 100644
--- a/docs/graphql/core/migrations/upgrade-v3.rst
+++ b/docs/graphql/core/migrations/upgrade-v3.rst
@@ -17,14 +17,15 @@ What has changed?
 -----------------
 
 Hasura now allows us to add multiple databases. This solves a variety of use cases.
-If we want to take advantage of multiple databases we'll have to use a config v3 project 
-which brings some changes to the project directory when compared to config v2.
+If we want to take advantage of multiple databases we'll have to use a ``config v3`` project 
+which brings some changes to the project directory when compared to ``config v2``.
 
 Let's try to understand what these changes are.
 
 Metadata directory
 ^^^^^^^^^^^^^^^^^^
-The following is a sample metadata directory when using config v3.
+
+The following is a sample metadata directory when using ``config v3``.
 
 .. code-block:: bash
 
@@ -75,9 +76,10 @@ it'll have a file of it's own.
 
 Currently CLI looks for ``!include`` directives in ``tables`` and ``functions`` keys only.
 
-Migrations Directory & Seeds Directory
+Migrations directory & Seeds directory
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There are some changes to ``migrations`` and ``seeds`` project directories in config V3. Projects will have child directories
+
+There are some changes to ``migrations`` and ``seeds`` project directories in ``config v3``. Projects will have child directories
 corresponding to migrations for each connected database. Look at the following example, the ```migrations`` directory
 has a sub directory ``default`` which corresponds to the connected database.
 
@@ -94,7 +96,7 @@ Changes needed in existing workflows
 
 With the introduction of multiple databases and it's configuration being in metadata, brings a change of workflow with it.
 
-The steps to apply migrations and metadata to a new hasura instance will be,
+The steps to apply migrations and metadata to a new hasura instance will be:
 
 .. code-block:: bash
   
@@ -105,15 +107,25 @@ The steps to apply migrations and metadata to a new hasura instance will be,
   # follow it with a metadata reload to make sure hasura is aware of the changes
   hasura metadata reload
 
-The reason why we have to do ``metadata apply`` first instead of ``migrate apply`` (that we are used to doing in config v2) is 
+The reason why we have to do ``metadata apply`` first instead of ``migrate apply`` (that we are used to doing in ``config v2``) is 
 If we do a ``migrate apply`` first then hasura might not be aware about the databases it has to connect to. Earlier we could not start hasura
 without a connected database, but now we can.
 
-Also, ``hasura seeds`` and ``hasura migrate`` now accepts a required flag ``--database``
+Also, ``hasura seeds`` and ``hasura migrate`` now accepts a required flag ``--database``.
 
 Upgrade steps
 -------------
 
+The latest version hasura CLI comes with a convenience script used to upgrade your CLI project to use ``config v3``. Note that this process is completely independent from your
+Hasura Graphql Engine server update process. 
+
+Pre update checklist / notes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. ``Config V3`` is expected to be used with Hasura GraphQL engine versions ``v2.0.0-alpha.1`` and above.
+2. During the update process CLI uses the server as the source of truth, so make sure your server is upto date.
+3. The update process replaces project metadata with metadata on the server.
+
 Step 0: Take a backup
 ^^^^^^^^^^^^^^^^^^^^^