(DOCSP-18316): Improve implicit default write concern docs

Author: jeff-allen-mongo

source/core/replica-set-rollbacks.txt

@@ -171,25 +171,26 @@ administrators can decide the next course of action to take.
 Avoid Replica Set Rollbacks
 ---------------------------
 
-For replica sets, the :doc:`write concern {w: 1}
-</reference/write-concern>` only provides acknowledgement of write
-operations on the primary. With the default write concern, data may be
-rolled back if the primary steps down before the write operations have
-replicated to any of the secondaries. This includes data written in
-:doc:`multi-document transactions </core/transactions>` that commit
-using :writeconcern:`"w: 1" <\<number\>>` write concern.
-
-.. include:: /includes/5.0-default-wc.rst
+For replica sets, the :doc:`write concern </reference/write-concern>`
+:writeconcern:`{ w: 1 } <\<number\>>` only provides acknowledgement of write
+operations on the primary. Data may be rolled back if the primary steps
+down before the write operations have replicated to any of the
+secondaries. This includes data written in :doc:`multi-document
+transactions </core/transactions>` that commit using
+:writeconcern:`{ w: 1 } <\<number\>>` write concern.
 
 Journaling and Write Concern ``majority``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To prevent rollbacks of data that have been acknowledged to the client,
-run all voting members with journaling enabled and use :ref:`w:
-majority write concern <wc-w>` to guarantee that the write operations
+run all voting members with journaling enabled and use :ref:`{ w:
+"majority" } write concern <wc-w>` to guarantee that the write operations
 propagate to a majority of the replica set nodes before returning with
 acknowledgement to the issuing client.
 
+Starting in MongoDB 5.0, ``{ w: "majority" }`` is the default write concern
+for *most* MongoDB deployments. See :ref:`wc-default-behavior`.
+
 .. include:: /includes/extracts/no-journaling-rollback.rst
 
 Visibility of Data That Can Be Rolled Back

source/includes/5.0-default-wc.rst

@@ -3,19 +3,57 @@ Starting in MongoDB 5.0, the implicit default write concern is
 considerations are made for deployments containing :ref:`arbiters
 <replica-set-arbiter-configuration>`:
 
-- If the number of data-bearing voting members is not strictly more
-  than the voting majority, the default write concern is ``w: 1``.
+- The voting majority of a replica set is 1 plus half the number of
+  voting members, rounded down. If the number of data-bearing voting
+  members is not greater than the voting majority, the default write
+  concern is ``{ w: 1 }``.
 
-- In all other scenarios, the default write concern is ``w:
-  "majority"``.
+- In all other scenarios, the default write concern is ``{ w:
+  "majority" }``.
 
 Specifically, MongoDB uses the following formula to determine the
 default write concern:
 
 .. code-block:: none
    :copyable: false
 
-   if [(#arbiters > 0) AND (#arbiters >= ½(#voting nodes) - 1)]
+   if [ (#arbiters > 0) AND (#non-arbiters <= majority(#voting-nodes)) ]
        defaultWriteConcern = { w: 1 }
    else
-       defaultWriteConcern = { w: majority }
+       defaultWriteConcern = { w: "majority" }
+
+For example, consider the following deployments and their respective
+default write concerns:
+
+.. list-table::
+   :header-rows: 1
+   
+   * - Non-Arbiters
+     - Arbiters
+     - Voting Nodes
+     - Majority of Voting Nodes
+     - Implicit Default Write Concern
+
+   * - 3
+     - 1
+     - 4
+     - 3
+     - ``{ w: 1 }``
+
+   * - 4
+     - 1
+     - 5
+     - 3
+     - ``{ w: "majority" }``
+
+- The first example has 3 non-arbiters and 1 arbiter for a total of 4
+  voting nodes. The majority of voting nodes (1 plus half of 4) is 3.
+  The number of non-arbiters (3) is less than or equal to the majority
+  of voting nodes, resulting in an implicit write concern of
+  ``{ w: 1 }``.
+
+- The second example has 4 non-arbiters and 1 arbiter for a total of 5
+  voting nodes. The majority of voting nodes (1 plus half of 5, rounded
+  down) is 3. The number of non-arbiters (4) is greater than the majority
+  of voting nodes, resulting in an implicit write concern of ``{ w:
+  "majority" }``.

source/reference/mongodb-defaults.txt

@@ -220,13 +220,6 @@ Default Write Concern
 
 .. include:: /includes/5.0-default-wc.rst
 
-.. note::
-
-   - With the default write concern, data can be rolled back.
-
-   - This write concern :red:`does not` guarantee :ref:`causal
-     consistency <sessions>`.
-
 .. _mongodb-default-wc-txns:
 
 .. _mongodb-default-wc-outside-transactions:

source/reference/write-concern.txt

@@ -82,8 +82,8 @@ available:
        the :ref:`calculated majority <calculating-majority-count>` of
        the data-bearing voting members (i.e. primary and secondaries
        with :rsconf:`members[n].votes` greater than ``0``).
-       ``w: majority`` is the default write concern for *most* MongoDB
-       configurations. See :ref:`wc-default-behavior`.
+       ``{ w: "majority" }`` is the default write concern for *most* MongoDB
+       deployments. See :ref:`wc-default-behavior`.
 
        For example, consider a replica set with 3 voting members,
        Primary-Secondary-Secondary (P-S-S). For this replica set,

source/release-notes/5.0.txt

@@ -667,12 +667,12 @@ Implicit Default Write Concern
 
 .. include:: /includes/5.0-default-wc.rst
 
-This default :doc:`write concern </reference/write-concern>` provides a 
-stronger durability guarantee in the event of an election, or if replica
-set members become unavailable.
+The ``{ w: "majority" }`` default :doc:`write concern
+</reference/write-concern>` provides a stronger durability guarantee in
+the event of an election, or if replica set members become unavailable.
 
 The :writeconcern:`w: majority <"majority">` write concern may impact 
-peformance since writes will only be acknowledged once a 
+performance since writes will only be acknowledged once a 
 :ref:`calculated majority <calculating-majority-count>` of replica set 
 members have executed and persisted the write to disk.