(DOCSP-27774): Improve discoverability of maxNumActiveUserIndexBuilds (#2488)

* (DOCSP-27774): Improve discoverability of maxNumActiveUserIndexBuilds parameter

* wording

* more wording adjustments

* update see also

* wording

* wording

* wording

* edits

Author: jeff-allen-mongo

source/core/index-creation.txt

@@ -127,6 +127,18 @@ To mitigate the risk of this occurrence, before creating the index:
 
    :ref:`index-creation-index-consistency`
 
+Maximum Concurrent Index Builds
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, the server allows up to three concurrent index builds. To
+change the number of allowed concurrent index builds, modify the
+:parameter:`maxNumActiveUserIndexBuilds` parameter.
+
+If the number of concurrent index builds reaches the limit specified by
+``maxNumActiveUserIndexBuilds``, the server blocks additional index
+builds until the number of concurrent index builds drops below the
+limit.
+
 Index Build Impact on Database Performance
 ------------------------------------------
 

source/reference/parameters.txt

@@ -1252,29 +1252,39 @@ General Parameters
 
    *Default*: 3
 
-   MongoDB limits the number of concurrent user index builds to control
-   WiredTiger cache pressure. The primary node can run up to
-   ``maxNumActiveUserIndexBuilds`` concurrent user index builds. This is
-   a global limit that applies across collections.
+   Sets the maximum number of concurrent index builds allowed on the
+   :term:`primary`. This is a global limit that applies across all
+   collections.
+   
+   Increasing the value of ``maxNumActiveUserIndexBuilds`` allows
+   additional concurrent index builds at the cost of increased pressure
+   on the WiredTiger cache.
 
    System indexes are not limited to ``maxNumActiveUserIndexBuilds``,
-   however a running system index build will count against the limit for
-   user index builds.
+   however a system index build counts against the limit for user index
+   builds.
 
-   After reaching ``maxNumActiveUserIndexBuilds``, MongodDB blocks
+   After the server reaches ``maxNumActiveUserIndexBuilds``, it blocks
    additional user index builds until the number of concurrent index
    builds drops below the ``maxNumActiveUserIndexBuilds`` limit. If an
-   index build is blocked, the server logs a message, "Too many index
-   builds running simultaneously, waiting until the number of active
-   index builds is below the threshold".
+   index build is blocked, the server logs this message:
+   
+   .. code-block:: sh
+      :copyable: false
+      
+      Too many index builds running simultaneously, waiting until the
+      number of active index builds is below the threshold.
 
    The following command sets a limit of 4 concurrent index builds:
 
    .. code-block:: javascript
 
       db.adminCommand( { setParameter: 1, maxNumActiveUserIndexBuilds: 4 } )
 
-   See also: :parameter:`maxIndexBuildMemoryUsageMegabytes`
+   See also:
+   
+   - :parameter:`maxIndexBuildMemoryUsageMegabytes`
+   - :ref:`index-creation-background`
 
 .. parameter:: notablescan