DOCSP-2680: reindex clarifications

Author: kay-kim

source/includes/driver-rebuild-indexes-tabs.rst

@@ -15,27 +15,34 @@ reIndex
    The :dbcommand:`reIndex` command drops all indexes on a
    collection and recreates them. This operation may be expensive for
    collections that have a large amount of data and/or a large number
-   of indexes. Use the following syntax:
+   of indexes. 
+
+   .. warning::
+
+      - For most users, the :dbcommand:`reIndex` command is unnecessary.
+
+      - Avoid running :dbcommand:`reIndex` for a replica set.
+
+      - Do not run :dbcommand:`reIndex` for a sharded cluster.
+
+   Use the following syntax:
 
    .. code-block:: javascript
 
       { reIndex: "collection" }
 
-   Normally, MongoDB compacts indexes during routine updates. For most
-   users, the :dbcommand:`reIndex` command is unnecessary. However, it
-   may be worth running if the collection size has changed significantly
-   or if the indexes are consuming a disproportionate amount of disk space.
+   The :binary:`~bin.mongo` shell provides a wrapper :method:`db.collection.reIndex()`.
 
-   Call :dbcommand:`reIndex` using the following form:
+Behavior
+--------
 
-   .. code-block:: javascript
+.. |cmd-name| replace:: :dbcommand:`reIndex`
+.. include:: /includes/note-reindex-impact-on-replica-sets.rst
+
+.. include:: /includes/important-reindex-locking.rst
 
-      db.collection.reIndex();
 
-   .. |cmd-name| replace:: :dbcommand:`reIndex`
-   .. include:: /includes/note-reindex-impact-on-replica-sets.rst
 
-   .. include:: /includes/important-reindex-locking.rst
 
 .. see:: :doc:`/core/index-creation` for more information on the
    behavior of indexing operations in MongoDB.

source/reference/command/reIndex.txt

@@ -17,17 +17,17 @@ db.collection.reIndex()
    collections that have a large amount of data and/or a large number
    of indexes.
 
-   Call this method, which takes no arguments, on a collection
-   object. For example:
+   .. warning::
 
-   .. code-block:: javascript
+      - For most users, the :method:`db.collection.reIndex()` operation
+        is unnecessary.
 
-      db.collection.reIndex()
+      - Avoid running :method:`db.collection.reIndex()` against a
+        collection in a replica set.
+
+      - Do not run :method:`db.collection.reIndex()` against a
+        collection in a sharded cluster.
 
-   Normally, MongoDB compacts indexes during routine updates. For most
-   users, the :method:`db.collection.reIndex()` is unnecessary. However, it
-   may be worth running if the collection size has changed significantly
-   or if the indexes are consuming a disproportionate amount of disk space.
 
 Behavior
 --------

source/reference/method/db.collection.reIndex.txt

@@ -45,17 +45,6 @@ Modify an Index
 
 .. include:: /includes/driver-examples/driver-example-modify-index-tabs.rst
 
-.. _rebuild-indexes:
-
-Rebuild Indexes
----------------
-
-.. |cmd-name| replace:: :method:`db.collection.reIndex()`
-
-.. |limit| replace:: :limit:`Maximum Index Key Length <Index Key>`
-
-.. include:: /includes/driver-rebuild-indexes-tabs.rst
-
 .. tabs-drivers::
 
    tabs:
@@ -64,4 +53,4 @@ Rebuild Indexes
          .. seealso::
 
             - :ref:`MongoDB Compass Documentation <compass-index>`
-            - `Compass Documentation for Indexes <https://docs.mongodb.com/compass/master/indexes/>`_
+            - `Compass Documentation for Indexes <https://docs.mongodb.com/compass/master/indexes/>`_