(DOCSP-45816)-Clarify-documentations-on-continuous-sync-v1.8-backport (532)

source/about-mongosync.txt

@@ -16,10 +16,8 @@ The :ref:`mongosync <c2c-mongosync>` binary is the primary process used in
 {+c2c-product-name+}. ``mongosync`` migrates data from a source cluster to a 
 destination cluster and keeps the clusters in continuous sync until you 
 :ref:`finalize <c2c-about-finalizing>` the sync. 
-
-You can use ``mongosync`` to create 
-dedicated analytics, development, or testing clusters that mirror your 
-production environment. 
+In addition to continuous data synchronization, ``mongosync`` can also
+perform a one time data migration between clusters.
 
 ``mongosync`` keeps track of its current actions through 
 :ref:`states <c2c-states>`. ``mongosync`` enters different states depending on 
@@ -38,6 +36,8 @@ and API operations:
    :alt: Diagram of relationship between ``mongosync`` states and API operations
    :figwidth: 600px
 
+The :ref:`Frequently Asked Questions (FAQ) <c2c-faq>` page addresses questions users have asked about ``mongosync``.
+
 Details
 -------
 

source/faq.txt

@@ -17,27 +17,30 @@ This page provides answers to some frequently asked questions we have
 encountered. If you have additional questions please contact MongoDB
 Support.
 
+.. _c2c-faq-read-write-during-sync:
+
 Can I perform reads or writes to my destination cluster while ``mongosync`` is syncing?
 ---------------------------------------------------------------------------------------
 
-You can perform reads during synchronization at any time. However, the data 
-that you read is :term:`eventually consistent <eventual consistency>`. For 
-consistent reads, wait for the migration to commit. To learn more, see 
-:ref:`mongosync-considerations`.
+You can perform reads at any time during synchronization. 
+However, ``mongosync`` combines and reorders writes from the source to destination during synchronization, 
+and also temporarily modifies various collection characteristics. 
+As a result, the destination is not guaranteed to match the source at any point in time when the sync is running. 
+For consistent reads, wait for the migration to :ref:`c2c-api-commit`. To learn more, see :ref:`mongosync-considerations`. 
+
+Performing writes to your destination cluster during synchronization results in undefined behavior. 
+To block writes on the destination cluster during sync, enable :ref:`write blocking <c2c-write-blocking>` when you :ref:`c2c-api-start` ``mongosync``.
 
-If you write to a synced namespace before issuing a :ref:`commit 
-<c2c-api-commit>` and while ``canWrite`` is ``false``, the behavior is 
-undefined. To ensure that you don't write to any synced namespaces, enable 
-:ref:`write blocking <c2c-write-blocking>`.
+Upon commit, it is only safe to write to the destination cluster when ``canWrite`` is ``true``. 
+To check the value of ``canWrite``, run the :ref:`c2c-api-progress` endpoint.
+
+To learn more about permissable reads and writes during synchronization, see :ref:`c2c-reads-and-writes`. 
 
 .. note::
 
    Index builds on the destination cluster are treated as writes 
    while ``mongosync`` is syncing.
 
-To check the value of ``canWrite``, call the :ref:`progress <c2c-api-progress>` 
-API endpoint.
-
 Can ``mongosync`` run on its own hardware? 
 ------------------------------------------
 

source/index.txt

@@ -8,15 +8,9 @@ Cluster-to-Cluster Sync
 
 {+c2c-product-name+} provides continuous data synchronization or a 
 one-time data migration between MongoDB clusters. For notes and caveats on 
-continuous sync, see the :ref:`<mongosync-considerations>` page. You can 
+continuous sync, see the :ref:`mongosync-considerations` page. You can
 enable {+c2c-product-name+} with the :ref:`mongosync <c2c-mongosync>` utility.
 
-``mongosync`` can continuously synchronize data between two clusters.
-You can use ``mongosync`` to create dedicated analytics, development,
-or testing clusters that mirror your production environment.
-Synchronized clusters can also support locality requirements for audit
-and data residency compliance. 
-
 For an overview of the ``mongosync`` process, see :ref:`about-mongosync`.
 
 To get started with ``mongosync``, refer to the :ref:`Quick Start Guide
@@ -27,8 +21,7 @@ restrictions and the :ref:`c2c-mongosync-behavior` page for behavior information
 
 .. include:: /includes/limitations-warning
 
-The :ref:`Frequently Asked Questions (FAQ) <c2c-faq>` page addresses
-common questions users have asked about ``mongosync``.
+The :ref:`Frequently Asked Questions (FAQ) <c2c-faq>` page addresses questions users have asked about ``mongosync``.
 
 .. toctree::
    :titlesonly:

source/reference/mongosync.txt

@@ -18,22 +18,19 @@ Definition
 ----------
 
 The ``mongosync`` binary is the primary process used in {+c2c-product-name+}. 
-``mongosync`` migrates data from one cluster to another and can keep the 
-clusters in continuous sync.
-
-You can use ``mongosync`` to create dedicated analytics, development,
-or testing clusters that mirror your production environment.
-Synchronized clusters can also support locality requirements for audit
-and data residency compliance. 
-
+``mongosync`` migrates data from a source cluster to a 
+destination cluster and keeps the clusters in continuous sync until you 
+:ref:`finalize <c2c-about-finalizing>` the sync. 
 In addition to continuous data synchronization, ``mongosync`` can also
-facilitate a one time data migration between clusters. 
+perform a one time data migration between clusters.
 
 For an overview of the ``mongosync`` process, see :ref:`about-mongosync`.
 
 To get started with ``mongosync``, refer to the :ref:`Quick Start Guide
 <c2c-quickstart>`.
 
+The :ref:`Frequently Asked Questions (FAQ) <c2c-faq>` page addresses questions users have asked about ``mongosync``.
+
 Compatibility
 -------------
 

source/reference/mongosync/mongosync-behavior.txt

@@ -115,6 +115,8 @@ Capped Collections
 
 .. include:: /includes/collections/behavior-capped-collections.rst
 
+.. _c2c-reads-and-writes: 
+
 Reads and Writes
 ----------------