feedback and restructure

Author: mayaraman19

source/includes/fact-mongosync-balancer.rst

@@ -1,10 +1,21 @@
 .. important::
 
-   When the source or destination cluster is a sharded cluster, you must stop 
-   the source cluster's balancer on collections within the :ref:`namespace
-   filter <c2c-filtered-sync>`. You can enable the source cluster's balancer on
-   the cluster level and for collections outside the namespace filter. 
-   You must also stop the destination cluster's balancer.
+   If the source or destination cluster is a sharded cluster
+   and you are not running ``mongosync`` with namespace filtering,
+   you must disable the source cluster's balancer
+   by running the :dbcommand:`balancerStop` command and waiting 15 minutes
+   for the command to complete.
+
+   If the source or destination cluster is a sharded cluster and you
+   are running ``mongosync`` with :ref:`namespace
+   filtering <c2c-filtered-sync>`, you can enable the source cluster's
+   balancer overall but you must disable it for 
+   all collections within the namespace filter. 
+   See :ref:`disabling-balancer-filtered`. You can also disable
+   the source cluster's balancer.
+
+   You must always disable the balancer on a sharded destination
+   cluster.
 
    During migration, do not run the :dbcommand:`moveChunk` or 
    :dbcommand:`moveRange` commands. If you have enabled the source cluster's

source/reference/limitations.txt

@@ -124,15 +124,22 @@ Sharded Clusters
      To check for index inconsistencies, see :ref:`Find Inconsistent
      Indexes Across Shards <manage-indexes-find-inconsistent-indexes>`.
 
-- When the source or destination cluster is a sharded cluster, you must stop 
-  the source cluster's balancer on collections within the :ref:`namespace
-  filter <c2c-filtered-sync>`. You can enable the source cluster's balancer on
-  the cluster level and for collections outside the namespace filter. 
-  If you are not running a filtered sync, you must stop the source cluster's
-  balancer.
-  You must also stop the destination cluster's balancer. See 
-  :ref:`enabling-balancer-filtered` to learn how to enable the balancer during
-  filtered sync.
+- If the source or destination cluster is a sharded cluster
+  and you are not running ``mongosync`` with namespace filtering,
+  you must disable the source cluster's balancer
+  by running the :dbcommand:`balancerStop` command and waiting 15 minutes
+  for the command to complete.
+
+  If the source or destination cluster is a sharded cluster and you
+  are running ``mongosync`` with :ref:`namespace
+  filtering <c2c-filtered-sync>`, you can enable the source cluster's
+  balancer overall but you must disable it for 
+  all collections within the namespace filter. 
+  See :ref:`disabling-balancer-filtered`. You can also disable
+  the source cluster's balancer.
+
+  You must always disable the balancer on a sharded destination
+  cluster.
 
 - If you have enabled the source cluster's
   balancer, but disabled it for collections within the namespace

source/reference/mongosync/mongosync-behavior.txt

@@ -102,39 +102,56 @@ preserve the source cluster's sharding configuration.
 
 .. include:: /includes/fact-mongosync-balancer.rst
 
-.. _enabling-balancer-filtered:
-
-Enabling Balancer in Filtered Sync
-''''''''''''''''''''''''''''''''''
-
-Before starting ``mongosync`` with a :ref:`namespace filter 
-<c2c-filtered-sync>`, enable the balancer for the source cluster
-by running the :method:`sh.startBalancer()` method in ``mongosh``. 
-Then, disable the balancer for each collection within the
-namespace filter by running the :dbcommand:`setAllowMigrations` command:
-
-.. code-block:: shell
-   
-   db.adminCommand(
-     { 
-       setAllowMigrations: “<db>.<collection>”,
-       allowMigrations: false
-     }
-   )
-
-Run the preceding command for every collection within the
-namespace filter.
-
-Then, run the :dbcommand:`balancerStop` command to stop
-the balancer on the destination cluster and wait for the command to complete.
-
-After stopping the balancer, wait fifteen minutes before
-starting ``mongosync``. This gives the cluster time to
-finish any in progress chunk migrations.
-
-If you enable the source cluster's balancer but do not use a
-namespace filter, or if you disable the balancer for all
-collections within the namespace filter, ``mongosync`` fails.
+.. _disabling-balancer-filtered:
+
+Disabling Balancer for Collections in Filtered Sync
+'''''''''''''''''''''''''''''''''''''''''''''''''''
+
+If you want to enable the balancer for collections that are not
+included in the namespace filter, use the following instructions before
+starting ``mongosync``. These instructions allow you to enable the balancer 
+for the source cluster and disable the balancer for collections 
+within the namespace filter.
+
+.. procedure::
+
+   .. step:: Enable the balancer for the source cluster.
+    
+      Before starting ``mongosync`` with a :ref:`namespace filter 
+      <c2c-filtered-sync>`, enable the balancer for the source cluster
+      by running the :method:`sh.startBalancer()` method in ``mongosh``.
+
+   .. step:: Disable the balancer for each collection.
+      
+      Disable the balancer for each collection within the
+      namespace filter by running the :dbcommand:`setAllowMigrations` command:
+
+      .. code-block:: shell
+        
+        db.adminCommand(
+          { 
+            setAllowMigrations: “<db>.<collection>”,
+            allowMigrations: false
+          }
+        )
+
+      Run the preceding command for every collection within the
+      namespace filter.
+
+   .. step:: Stop the balancer on the destination cluster.
+
+      Run the :dbcommand:`balancerStop` command to stop
+      the balancer on the destination cluster and wait 
+      for the command to complete.
+      After stopping the balancer, wait **fifteen minutes** before
+      starting ``mongosync``. This gives the cluster time to
+      finish any in progress chunk migrations.
+
+.. important:: 
+
+   If you enable the source cluster's balancer but do not use a
+   namespace filter, or if you do not disable the balancer for all
+   collections within the namespace filter, ``mongosync`` fails.
 
 Pre-Split Chunks
 ''''''''''''''''