Improve docs of use_checkpoints and checkpoint_interval config options.merge-rebase-target

1 files changed, 12 insertions, 16 deletions

diff --git a/share/doc/src/config/replicator.rst b/share/doc/src/config/replicator.rst
index 515c6797f..388491ce3 100644
--- a/share/doc/src/config/replicator.rst
+++ b/share/doc/src/config/replicator.rst
@@ -116,37 +116,33 @@ Replicator Database Configuration
     .. versionadded:: 1.6
 
     Defines replication checkpoint interval in milliseconds. :ref:`Replicator
-    <replication/replicator>` will :get:`requests </{db}>` Source database
-    each time after a specified amount of interval::
+    <replicator>` will :get:`requests </{db}>` from the Source database at
+    the specified interval::
 
       [replicator]
       checkpoint_interval = 5000
 
-    Keeping this value lower raises polling rate to Source database, which
-    may be useful for frequently changing data, while higher value saves
-    traffic usage that is important for mobile clients.
+    Lower intervals may be useful for frequently changing data, while higher
+    values will lower bandwidth and make fewer requests for infrequently
+    updated databases.
 
 
   .. config:option:: use_checkpoints
 
      .. versionadded:: 1.6
 
-     If set as ``true`` CouchDB makes intermediate checkpoints during
-     replication from those it may continue it in case of failure or restart::
+     If ``use_checkpoints`` is set to ``true``, CouchDB will make checkpoints
+     during replication and at the completion of replication. CouchDB can
+     efficiently resume replication from any of these checkpoints::
 
       [replicator]
       use_checkpoints = true
 
-     .. warning:: It's **not recommended** to switch this option off
-        (by setting value ``false`` to it) since without checkpoints there would
-        not be stored any replication history logs both on Source and Target,
-        forcing replication to start from the very beginning.
+     .. note:: Checkpoints are stored in :ref:`local documents <api/local>`
+        on both the source and target databases (which requires write access).
 
-     .. note:: Checkpoints (aka Replication Log) are stored as :ref:`local
-        documents <api/local>` both on Source and Target endpoints. In case,
-        when client has no write permission on Source database you may disable
-        them, but locally for specific replication process.
-        See :ref:`replication-settings` for more info.
+     .. warning:: Disabling checkpoints is **not recommended** as CouchDB
+        will scan the Source database's changes feed from the beginning.
 
 
   .. config:option:: cert_file