DOCS-983 splitting chunks

Author: Bob Grabar

source/reference/command/split.txt

@@ -12,12 +12,20 @@ split
    this command makes it possible for administrators to manually
    create splits.
 
-   .. admonition:: In normal operation there is no need to manually split chunks
-
-      The :term:`balancer` and other sharding infrastructure will
-      automatically create chunks in the course of normal
-      operations. See :doc:`/core/sharded-cluster-internals` for more
-      information.
+   In normal operation there is no need to manually split chunks. The
+   :term:`balancer` and other sharding infrastructure will automatically
+   create chunks in the course of normal operations. See
+   :doc:`/core/sharded-cluster-internals` for more information.
+
+.. warning::
+
+   Be careful when splitting chunks. When you shard a collection that
+   has existing data, MongoDB automatically creates chunks to evenly
+   spread the collection. Performing additional splits requires
+   knowledge of the resulting chunk sizes by numbers of documents and by
+   size. You do not want splits that cause some chunks to be much larger
+   than others. This leads to balancing based on count of chunks, not on
+   their size, which may cause extreme load/data-distribution problems.
 
    Consider the following example:
 

source/reference/command/splitChunk.txt

@@ -10,4 +10,14 @@ splitChunk
    :method:`sh.splitFind()` and :method:`sh.splitAt()` functions in the
    :program:`mongo` shell to access this functionality.
 
+.. warning::
+
+   Be careful when splitting chunks. When you shard a collection that
+   has existing data, MongoDB automatically creates chunks to evenly
+   spread the collection. Performing additional splits requires
+   knowledge of the resulting chunk sizes by numbers of documents and by
+   size. You do not want splits that cause some chunks to be much larger
+   than others. This leads to balancing based on count of chunks, not on
+   their size, which may cause extreme load/data-distribution problems.
+
    .. admin-only.

source/tutorial/manage-chunks-in-sharded-cluster.txt

@@ -58,6 +58,16 @@ You may want to split chunks manually if:
    values between ``300`` and ``400``, *but* all values of your shard
    keys are between ``250`` and ``500`` are in a single chunk.
 
+.. warning::
+
+   Be careful when splitting chunks. When you shard a collection that
+   has existing data, MongoDB automatically creates chunks to evenly
+   spread the collection. Performing additional splits requires
+   knowledge of the resulting chunk sizes by numbers of documents and by
+   size. You do not want splits that cause some chunks to be much larger
+   than others. This leads to balancing based on count of chunks, not on
+   their size, which may cause extreme load/data-distribution problems.
+
 Use :method:`sh.status()` to determine the current chunks ranges across
 the cluster.
 
@@ -101,11 +111,13 @@ chunk splits.
 Create Chunks (Pre-Splitting)
 -----------------------------
 
+Pre-splitting lets you preemptively split chunks in an empty collection
+and is used *only* in certain situations.
 In most situations a :term:`sharded cluster` will create and distribute
 chunks automatically without user intervention. However, in a limited
 number of use profiles, MongoDB cannot create enough chunks or
-distribute data fast enough to support required throughput. Consider
-the following scenarios:
+distribute data fast enough to support required throughput.
+For example, if:
 
 - you must partition an existing data collection that resides on a
   single shard.
@@ -123,7 +135,7 @@ the following scenarios:
 Preemptively splitting chunks increases cluster throughput for these
 operations, by reducing the overhead of migrating chunks that hold
 data during the write operation. MongoDB only creates splits after an
-insert operation, and can only migrate a single chunk at a time. Chunk
+insert operation and can migrate only a single chunk at a time. Chunk
 migrations are resource intensive and further complicated by large
 write volume to the migrating chunk.