DOCS-293 review edits

Author: Bob Grabar

source/administration/sharding.txt

@@ -770,8 +770,11 @@ to pre-splitting.
 .. index:: bulk insert
 .. _sharding-bulk-inserts:
 
-Bulk Inserts and Sharding
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Bulk Insert Strategies
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. todo Consider moving to the administrative guide as it's of an applied nature,
+   or create an applications document for sharding
 
 .. todo link the words "bulk insert" to the bulk insert topic when it's
    published
@@ -788,53 +791,43 @@ the following:
   :program:`mongos` instances. If the collection is empty, pre-split
   first, as described in :ref:`sharding-administration-pre-splitting`.
 
-Monotonically Increasing Shard Key Values
-`````````````````````````````````````````
-
-If your shard key monotonically increases during an insert then all the
-inserts will go to the last chunk in the collection. The system will
-adjust the metadata to keep balance, but at a given time ``t`` all
-writes will be going to a single shard, which is undesirable if insert
-rate is extremely large. A large insert is one in which the insert
-volume is beyond the range that a single shard can process at a given
-point in time. Increasing values are fine if the insert volume is within
-the range the shard can process.
-
-To avoid sending more writes than a shard can process, use a shard key
-that is not increasing in value. For example in some cases you could
-reverse all the bits of your shard key, which preserves information
-while avoiding the increasing sequence of values.
-
-:term:`BSON` :term:`ObjectIds <ObjectId>` are one case of a value that
-monotonically increases during an insert. If you use :term:`ObjectId` as
-a shard key, then you can do either of the following at generation time
-to more evenly distribute inserts based on this property:
-
-- Reverse the bits of the ObjectIds, or
-- Swap the first and last 16-bit words, to "shuffle" the inserts.
-- Use UUIDs instead, but check that your UUID generator does not
-  generate consistent increasing UUIDs, which would cause the same
-  behavior.
-
-.. example:: The following example, in C++, swaps the leading and
-   trailing 16-bit word of object IDs generated so that they are no
-   longer monotonically increasing.
-
-   .. code-block:: none
-
-      using namespace mongo;
-      OID make_an_id() {
-        OID x = OID::gen();
-        const unsigned char *p = x.getData();
-        swap( (unsigned short&) p[0], (unsigned short&) p[10] );
-        return x;
-      }
-
-      void foo() {
-        // create an object
-        BSONObj o = BSON( "_id" << make_an_id() << "x" << 3 << "name" << "jane" );
-        // now we might insert o into a sharded collection...
-      }
+- If your shard key monotonically increases during an insert then all
+  the inserts will go to the last chunk in the collection, which is
+  undesirable if the insert volume is beyond the range that a single
+  shard can process at a given point in time.
+
+  If the insert volume exceeds that range, and if you can't avoid
+  picking a monotonically increasing shard key, then you can do either
+  of the following at generation time to more evenly distribute inserts:
+
+  - Reverse all the bits of your shard key, which preserves information
+    while avoiding the increasing sequence of values.
+  - Swap the first and last 16-bit words, to "shuffle" the inserts.
+
+  .. example:: The following example, in C++, swaps the leading and
+     trailing 16-bit word of :term:`BSON` :term:`ObjectIds <ObjectId>`
+     generated so that they are no longer monotonically increasing.
+
+     .. code-block:: cpp
+
+        using namespace mongo;
+        OID make_an_id() {
+          OID x = OID::gen();
+          const unsigned char *p = x.getData();
+          swap( (unsigned short&) p[0], (unsigned short&) p[10] );
+          return x;
+        }
+
+        void foo() {
+          // create an object
+          BSONObj o = BSON( "_id" << make_an_id() << "x" << 3 << "name" << "jane" );
+          // now we might insert o into a sharded collection...
+        }
+
+  For information on choosing a shard key, see :ref:`sharding-shard-key`
+  and see :ref:`Shard Key Internals <sharding-internals-shard-keys>` (in
+  particular, :ref:`sharding-internals-operations-and-reliability` and
+  :ref:`sharding-internals-choose-shard-key`).
 
 .. index:: balancing; operations
 .. _sharding-balancing-operations:

source/core/sharding-internals.txt

@@ -190,6 +190,8 @@ wait for a response from every shard before it can merge the results
 and return data. If you require high performance sorted queries,
 ensure that the sort key is a component of the shard key.
 
+.. _sharding-internals-operations-and-reliability:
+
 Operations and Reliability
 ~~~~~~~~~~~~~~~~~~~~~~~~~~