DOCSP-25487 update transaction docs (#5448) (#5506)

* DOCSP-25487 update transaction docs (#5448)

* General version and term cleanup

* More deprecated version info cleanup, clarified collection creation is implicit if none exists

* Fixed line break

* Cleaned up Transactions and Operations topic

* Lingering mention of collection reqs

* Indentation fixes

* Fixed indentation

* Internal PR feedback

* Externalized common content to includes

* Internal review feedback

* Typo fix

* Fixed a ref

Author: nvillahermosa-mdb

source/core/transactions-operations.txt

@@ -18,12 +18,6 @@ For transactions:
 
 .. include:: /includes/extracts/transactions-operations-crud.rst
 
-Operations that affect the database catalog, such as creating or
-dropping a collection or an index, are not allowed in multi-document
-transactions. For example, a multi-document transaction cannot include
-an insert operation that would result in the creation of a new
-collection. See :ref:`transactions-operations-ref-restricted`.
-
 Operations Supported in Multi-Document Transactions
 ---------------------------------------------------
 
@@ -38,11 +32,11 @@ The following read/write operations are allowed in transactions:
 
 .. note:: Updates to Shard Key Values
 
-   Starting in MongoDB 4.2, you can update a document's shard key value
-   (unless the shard key field is the immutable ``_id`` field) by
-   issuing single-document update/findAndModify
-   operations either in a transaction or as a :doc:`retryable write
-   </core/retryable-writes>`. For details, see :ref:`update-shard-key`.
+   You can update a document's shard key value (unless the shard key
+   field is the immutable ``_id`` field) by issuing single-document
+   update / findAndModify operations either in a transaction or as a
+   :doc:`retryable write </core/retryable-writes>`. For details, see
+   :ref:`update-shard-key`.
 
 .. _transactions-operations-count:
 
@@ -63,10 +57,7 @@ Distinct Operation
 Administration Operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Starting in MongoDB 4.4 with :ref:`feature compatibility version (fcv)
-<view-fcv>` ``"4.4"``, you can create collections and indexes inside a
-:doc:`multi-document transaction </core/transactions>` if the
-transaction is :red:`not` a cross-shard write transaction. 
+.. include:: /includes/transactions/create-collections-indexes-in-transaction.rst
 
 .. _transactions-operations-ddl-explicit:
 

source/core/transactions.txt

@@ -15,18 +15,18 @@ Transactions
    :class: twocols
 
 .. meta::
-   :description: For situations that require atomicity of reads and writes to multiple documents (in a single or multiple collections), MongoDB supports multi-document transactions.
+   :description: For situations that require atomicity of reads and writes to multiple documents (in a single or multiple collections), MongoDB supports multi-document transactions, also called distributed transactions.
    :keywords: MongoDB, transactions, distributed transactions, MongoDB multi-document transactions, MongoDB multi-statement transactions, java transaction examples, python transaction examples, node transaction examples, php transaction examples, scala transaction examples, csharp transaction examples, perl transaction examples, ruby transaction examples
 
 In MongoDB, an operation on a single document is atomic. Because you can
 use embedded documents and arrays to capture relationships between data
 in a single document structure instead of normalizing across multiple
 documents and collections, this single-document atomicity obviates the
-need for multi-document transactions for many practical use cases.
+need for distributed transactions for many practical use cases.
 
 For situations that require atomicity of reads and writes to multiple
 documents (in a single or multiple collections), MongoDB supports
-multi-document transactions. With distributed transactions,
+distributed transactions. With distributed transactions,
 transactions can be used across multiple operations, collections,
 databases, documents, and shards.
 
@@ -333,32 +333,10 @@ This example highlights the key components of the transactions API.
 Transactions and Atomicity
 --------------------------
 
-.. note:: Distributed Transactions and Multi-Document Transactions
+.. include:: /includes/transactions/distributed-transaction-repl-shard-support.rst
 
-   Starting in MongoDB 4.2, the two terms are synonymous. Distributed
-   transactions refer to multi-document transactions on sharded
-   clusters and replica sets. Multi-document transactions (whether on
-   sharded clusters or replica sets) are also known as distributed
-   transactions starting in MongoDB 4.2.
-
-For situations that require atomicity of reads and writes to multiple
-documents (in a single or multiple collections), MongoDB supports
-multi-document transactions:
-
-- **In version 4.0**, MongoDB supports multi-document transactions on
-  replica sets.
-
-- **In version 4.2**, MongoDB introduces distributed transactions,
-  which adds support for multi-document transactions on sharded
-  clusters and incorporates the existing support for
-  multi-document transactions on replica sets.
-
-  To use transactions on MongoDB 4.2 deployments (replica sets and
-  sharded clusters), clients :red:`must` use MongoDB drivers updated for
-  MongoDB 4.2.
-
-Multi-document transactions are atomic (i.e. provide an
-"all-or-nothing" proposition):
+Distributed transactions are atomic. They provide an "all-or-nothing" 
+proposition:
 
 - When a transaction commits, all data changes made in the transaction
   are saved and visible outside the transaction. That is, a transaction
@@ -384,7 +362,7 @@ Transactions and Operations
 ---------------------------
 
 Distributed transactions can be used across multiple operations,
-collections, databases, documents, and, starting in MongoDB 4.2, shards.
+collections, databases, documents, and shards.
 
 For transactions:
 
@@ -404,12 +382,14 @@ For a list of operations not supported in transactions, see
 Create Collections and Indexes In a Transaction
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Starting in MongoDB 4.4 with :ref:`feature compatibility version (fcv)
-<view-fcv>` ``"4.4"``, you can create collections and indexes inside a
-:doc:`multi-document transaction </core/transactions>` unless the
-transaction is a cross-shard write transaction. With ``"4.2"`` or less,
-operations that affect the database catalog, such as creating or
-dropping a collection or an index, are :red:`disallowed` in transactions.
+You can perform the following operations inside of a :ref:`distributed
+transaction <transactions>` as long as the transaction is not a
+cross-shard write transaction:
+
+- Create collections.
+
+- Create indexes on new empty collections created earlier in the same
+  transaction.
 
 When creating a collection inside a transaction:
 
@@ -512,8 +492,7 @@ Restricted Operations
 Transactions and Sessions
 -------------------------
 
-- Transactions are associated with a session; i.e. you start a
-  transaction for a session.
+- Transactions are associated with a session
 
 - At any given time, you can have at most one open transaction for a
   session.
@@ -591,20 +570,17 @@ Transactions support the following read concern levels:
 ``"majority"``
 ``````````````
 
-- Read concern :readconcern:`"majority"` returns data that has been
-  acknowledged by a majority of the replica set members (i.e. data
-  cannot be rolled back) **if** the transaction commits with
-  :ref:`write concern "majority" <transactions-write-concern>`.
-
-- If the transaction does not use :ref:`write concern "majority"
-  <transactions-write-concern>` for the commit, the
-  :readconcern:`"majority"` read concern provides **no** guarantees that
-  read operations read majority-committed data.
+- If the transaction commits with :ref:`write concern "majority"
+  <transactions-write-concern>`, read concern :readconcern:`"majority"`
+  returns data that has been acknowledged by a majority of the replica
+  set members and can't be rolled back. Otherwise, read concern
+  :readconcern:`"majority"` provides no guarantees that read operations
+  read majority-committed data.
 
-- For transactions on sharded cluster, :readconcern:`"majority"` read
-  concern cannot guarantee that the data is from the same snapshot
-  view across the shards. If snapshot isolation is required, use
-  :ref:`transactions-read-concern-snapshot` read concern.
+- For transactions on sharded cluster, read concern
+  :readconcern:`"majority"` can't guarantee that the data is from the 
+  same snapshot view across the shards. If snapshot isolation is
+  required, use read concern :ref:`transactions-read-concern-snapshot`.
 
 .. _transactions-read-concern-snapshot:
 
@@ -686,7 +662,7 @@ values, including:
 
 - Write concern :writeconcern:`w: "majority" <"majority">` returns
   acknowledgement after the commit has been applied to a majority
-  (M) of voting members; i.e. the commit has been applied to the
+  (M) of voting members, meaning the commit has been applied to the
   primary and (M-1) voting secondaries.
 
 - When you commit with :writeconcern:`w: "majority" <"majority">`
@@ -809,7 +785,7 @@ MongoDB provides various transactions metrics:
 
    * - :binary:`~bin.mongod` and :binary:`~bin.mongos` log messages
 
-     - Includes information on slow transactions (i.e. transactions
+     - Includes information on slow transactions, which are transactions
        that exceed the :setting:`operationProfiling.slowOpThresholdMs`
        threshold) under the :data:`TXN` log component.