DOCS-461 review edits II

Author: Bob Grabar

source/reference/command/moveChunk.txt

@@ -32,8 +32,8 @@ moveChunk
    :param _secondaryThrottle: Optional. Set to ``false`` by default. If
                               set to ``true``, the balancer waits for
                               replication to :ref:`secondaries
-                              <secondary>` before migrating chunks. For
-                              details, see
+                              <secondary>` while copying and deleting
+                              data during migrations. For details, see
                               :ref:`sharded-cluster-config-secondary-throttle`.
 
    Use the :method:`sh.moveChunk()` helper in the :program:`mongo`

source/tutorial/configure-sharded-cluster-balancer.txt

@@ -18,51 +18,6 @@ is necessary, this page describes settings that can be changed.
 For conceptual information about the balancer, see
 :ref:`sharding-balancing` and :ref:`sharding-balancing-internals`.
 
-.. index:: balancing; secondary throttle
-.. index:: secondary throttle
-.. _sharded-cluster-config-secondary-throttle:
-
-Require Replication before Chunk Migration (Secondary Throttle)
----------------------------------------------------------------
-
-.. versionadded:: 2.2.1
-
-You can configure the balancer to wait for replication to secondaries
-during migrations. You do so by enabling the balancer's
-``_secondaryThrottle`` parameter, which reduces throughput (i.e.,
-"throttles") in order to decrease the load on secondaries. You might do
-this, for example, if you have migration-caused I/O peaks that impact
-other workloads
-
-When enabled, secondary throttle puts a ``{ w : 2 }`` write concern on
-deletes and on copies, which means the balancer waits for those
-operations to replicate to at least one secondary before migrating
-chunks.
-
-.. BACKGROUND NOTES
-   Specifically, secondary throttle affects the first and fourth
-   phases (informal phases) of chunk migration. Migration can happen during
-   the second and third phases (the "steady state"):
-   1) copies the documents in the chunk from shardA to shardB
-   2) continues to copy over ongoing changes that occurred during the initial copy step,
-      as well as current changes to that chunk range
-   3) Stop writes, allow shardB to get final changes, commit migration to config server
-   4) cleanup now-inactive data on shardA in chunk range (once all cursors are done)
-
-You enable ``_secondaryThrottle`` directly in the
-:data:`settings <~config.settings>` collection in the :ref:`config database
-<config-database>` by running the following commands from the
-:program:`mongo` shell:
-
-.. code-block:: javascript
-
-   use config
-   db.settings.update( { "_id" : "balancer" } , { $set : { "_secondaryThrottle" : true } } )
-
-You also can enable secondary throttle when issuing the
-:dbcommand:`moveChunk` command by setting ``_secondaryThrottle`` to
-``true``. For more information, see :dbcommand:`moveChunk`.
-
 .. _sharded-cluster-config-balancing-window:
 
 Schedule a Window of Time for Balancing to Occur
@@ -84,7 +39,7 @@ Configure Default Chunk Size
 ----------------------------
 
 The default chunk size for a sharded cluster is 64 megabytes. In most
-situations, the default size is optimal for splitting and migrating
+situations, the default size is appropriate for splitting and migrating
 chunks. For information on how chunk size affects deployments, see
 details, see :ref:`sharding-chunk-size`.
 
@@ -102,9 +57,10 @@ The ``maxSize`` field in the :data:`~config.shards` collection in the
 :ref:`config database <config-database>` sets the maximum size for a
 shard, allowing you to control whether the balancer will migrate chunks
 to a shard. If :data:`dataSize <~dbStats.dataSize>` is above a shard's
-``maxSize``, the balancer will not move chunks to the shard. The
-balancer also will not move chunks off the shard. The ``maxSize`` value
-only affects the balancer's selection of destination shards.
+``maxSize``, the balancer will not move chunks to the shard. Also, the
+balancer will not move chunks off an overloaded shard. This must happen
+manually. The ``maxSize`` value only affects the balancer's selection of
+destination shards.
 
 By default, ``maxSize`` is not specified, allowing shards to consume the
 total amount of available space on their machines if necessary.
@@ -140,7 +96,7 @@ megabytes.
    .. code-block:: javascript
 
       use config
-      db.shards.update( { _id : "shard0000" }, { $set : { maxSize : 125 } }, { upsert: true } )
+      db.shards.update( { _id : "shard0000" }, { $set : { maxSize : 125 } } )
 
    To later increase the ``maxSize`` setting to 250 megabytes, run the
    following:
@@ -149,3 +105,48 @@ megabytes.
 
       use config
       db.shards.update( { _id : "shard0000" }, { $set : { maxSize : 250 } } )
+
+.. index:: balancing; secondary throttle
+.. index:: secondary throttle
+.. _sharded-cluster-config-secondary-throttle:
+
+Require Replication before Chunk Migration (Secondary Throttle)
+---------------------------------------------------------------
+
+.. versionadded:: 2.2.1
+
+You can configure the balancer to wait for replication to secondaries
+during migrations. You do so by enabling the balancer's
+``_secondaryThrottle`` parameter, which reduces throughput (i.e.,
+"throttles") in order to decrease the load on secondaries. You might do
+this, for example, if you have migration-caused I/O peaks that impact
+other workloads
+
+When enabled, secondary throttle puts a ``{ w : 2 }`` write concern on
+deletes and on copies, which means the balancer waits for those
+operations to replicate to at least one secondary before migrating
+chunks.
+
+.. BACKGROUND NOTES
+   Specifically, secondary throttle affects the first and fourth
+   phases (informal phases) of chunk migration. Migration can happen during
+   the second and third phases (the "steady state"):
+   1) copies the documents in the chunk from shardA to shardB
+   2) continues to copy over ongoing changes that occurred during the initial copy step,
+      as well as current changes to that chunk range
+   3) Stop writes, allow shardB to get final changes, commit migration to config server
+   4) cleanup now-inactive data on shardA in chunk range (once all cursors are done)
+
+You enable ``_secondaryThrottle`` directly in the
+:data:`settings <~config.settings>` collection in the :ref:`config database
+<config-database>` by running the following commands from the
+:program:`mongo` shell:
+
+.. code-block:: javascript
+
+   use config
+   db.settings.update( { "_id" : "balancer" } , { $set : { "_secondaryThrottle" : true } , { upsert : true } } )
+
+You also can enable secondary throttle when issuing the
+:dbcommand:`moveChunk` command by setting ``_secondaryThrottle`` to
+``true``. For more information, see :dbcommand:`moveChunk`.