(DOCSP-23728): Clarify manage indexes behavior (#1443) (#1453)

* WIP

* (DOCSP-23728): Clarify manage indexes behavior

* typo fix

* add 'success' step

* formatting

* edits

* move tip

* edits

* add clarification

* add clarity to steps

* typo

* remove extra word

* address review feedback

* minor edit

* wording

* updates per review feedback

* wording

Author: jeff-allen-mongo

source/core/index-hidden.txt

@@ -121,6 +121,8 @@ The operation returns the following information:
 
 The index option ``hidden`` is only returned if the value is ``true``.
 
+.. _hide-existing-index:
+
 Hide an Existing Index
 ~~~~~~~~~~~~~~~~~~~~~~
 

source/includes/driver-examples/driver-example-modify-index-tabs.rst

@@ -3,13 +3,13 @@
    tabs:
      - id: shell
        content: |
-         To modify an existing index, you need to drop and recreate the
-         index. The exception to this rule is
+         To modify an existing index in the MongoDB Shell, you need to
+         drop and recreate the index. The exception to this rule is
          :doc:`TTL indexes </core/index-ttl/>`, which can be modified
          via the :dbcommand:`collMod` command in conjunction with the
          :collflag:`index` collection flag.
 
      - id: compass
        content: |
          To modify an existing index in |compass|, you need to drop and
-         recreate the index.
+         recreate the index.

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

@@ -3,13 +3,13 @@
    tabs:
      - id: shell
        content: |
-         MongoDB provides two methods for removing indexes from a collection:
+         
+         When removing indexes in the MongoDB Shell, you can either:
 
-         - :method:`db.collection.dropIndex()` and
+         - Remove a specific index.
 
-         - :method:`db.collection.dropIndexes()`
+         - Remove all indexes from the collection.
 
- 
          Remove Specific Index
          ~~~~~~~~~~~~~~~~~~~~~
 
@@ -67,16 +67,15 @@
 
      - id: compass
        content: |
+
          To remove an index from a collection in |compass|:
 
-         1. Navigate to the collection on which the target
-            index exists.
+         1. Navigate to the collection containing the target index.
 
          2. Click the :guilabel:`Indexes` tab.
 
-         3. Click the :guilabel:`trash can` icon in the
-            :guilabel:`Drop` column for the index you wish to delete.
+         3. In the :guilabel:`Drop` column for the target index, click
+            the trash icon.
 
          .. figure:: /images/compass-delete-index.png
             :alt: Delete an index in Compass
-

source/tutorial/manage-indexes.txt

@@ -35,26 +35,146 @@ View Existing Indexes
 Remove Indexes
 --------------
 
+.. tip:: Hide an Index Before Dropping It
+
+   If you drop an index that is actively used in production, your
+   application may incur a performance degradation. Before you drop an
+   index, you can evaluate the potential impact of the drop by
+   :ref:`hiding the index <hide-existing-index>`.
+   
+   Hidden indexes are not used to support queries. If you hide an index
+   and observe substantial negative performance impact, consider keeping
+   and unhiding the index so queries can resume using it.
+
 .. include:: /includes/driver-remove-indexes-tabs.rst
 
 Modify an Index
 ---------------
 
 .. include:: /includes/driver-examples/driver-example-modify-index-tabs.rst
 
-.. tabs-drivers::
+Minimize Performance Impact With a Temporary Index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you drop an index that is actively used in production, your
+application may incur a performance degradation. To ensure queries can
+still use an index during modification, you can create a temporary,
+redundant index that contains the same fields as the modified index.
+
+Example
+```````
+
+This example creates a new index and modifies that index to make it
+:ref:`unique <index-type-unique>`.
+
+.. procedure::
+   :style: normal
+
+   .. step:: Create a ``siteAnalytics`` collection with an index on the ``url`` field
+
+      Run this command:
+
+      .. code-block:: javascript
+
+         db.siteAnalytics.createIndex( { "url": 1 } )
+
+      The command returns the name of the index:
+
+      .. code-block:: javascript
+         :copyable: false
+
+         url_1
+
+   .. step:: Create a temporary index that contains the ``url`` field
+
+      Run this command:
+
+      .. code-block:: javascript
+
+         db.siteAnalytics.createIndex( { "url": 1, "dummyField": 1 } )
+
+      The command returns the name of the index:
+
+      .. code-block:: javascript
+         :copyable: false
+
+         url_1_dummyField_1
+
+      This temporary index lets you safely drop the original ``{ "url":
+      1 }`` index without impacting performance.
+
+   .. step:: Drop the original index
+
+      Run this command:
+
+      .. code-block:: javascript
+
+         db.siteAnalytics.dropIndex( { "url": 1 } )
+
+      The command returns:
+
+      .. code-block:: javascript
+         :copyable: false
+
+         { nIndexesWas: 3, ok: 1 } 
+
+   .. step:: Recreate the ``{ "url": 1 }`` index with the ``unique`` property
+
+       Run this command:
+
+       .. code-block:: javascript
+
+         db.siteAnalytics.createIndex( { "url": 1 }, { "unique": true } )
+         
+       The command returns the name of the index:
+
+       .. code-block:: javascript
+          :copyable: false
+
+          url_1
+         
+       The ``url_1`` index is recreated and you can drop the temporary
+       index without impacting performance. Queries on the ``url`` field
+       can use the new unique index.
+
+   .. step:: Drop the temporary index
+
+      Run this command:
+
+      .. code-block:: javascript
+
+         db.siteAnalytics.dropIndex( { "url": 1, "dummyField": 1 } )
+
+      The command returns:
+
+      .. code-block:: javascript
+         :copyable: false
+
+         { nIndexesWas: 3, ok: 1 } 
+
+   .. step:: Confirm that the index was updated
+
+      To view the indexes on the ``siteAnalytics`` collection, run this
+      command:
+
+      .. code-block:: javascript
+
+         db.siteAnalytics.getIndexes()
+
+      The command returns these indexes, indicating that the ``url_1``
+      index is now unique:
 
-   tabs:
-     - id: compass
-       content: |
-         .. seealso::
+      .. code-block:: javascript
+         :copyable: false
 
-            - :ref:`MongoDB Compass Documentation <compass-index>`
-            - :compass:`Compass Documentation for Indexes </indexes/>`
+         [
+           { v: 2, key: { _id: 1 }, name: '_id_' },
+           { v: 2, key: { url: 1 }, name: 'url_1', unique: true }
+         ]       
 
 .. _manage-indexes-find-inconsistent-indexes:
 
-Find Inconsistent Indexes across Shards
+Find Inconsistent Indexes Across Shards
 ---------------------------------------
 
 A sharded collection has an inconsistent index if the collection does