docs: update the updates

3 files changed, 24 insertions, 13 deletions

diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index 739f7d8a8..52dc32d13 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -21,11 +21,17 @@
 .. http:head:: /{db}/_changes
 .. http:post:: /{db}/_changes
 
-  A sorted list of changes made to documents in the database, in the order
-  they were made, can be obtained from the database's ``_changes`` resource.
+  A sorted list of changes made to documents in the database, in time order of
+  application, can be obtained from the database's ``_changes`` resource. Only
+  the most recent change for a given document is guaranteed to be provided,
+  for example if a document has had fields added, and then deleted, an API
+  client checking for changes will not necessarily receive the intermediate
+  state of added documents.
 
   This can be used to listen for update and modifications to the database for
-  post processing or synchronization.
+  post processing or synchronization, and for practical purposes, a continuously
+  connected ``_changes`` feed is a reasonable approach for generating a
+  real-time log for most applications.
 
   :param db: Database name
   :<header Accept: - :mimetype:`application/json`
@@ -289,7 +295,7 @@ Event Source
 
 The `eventsource` feed provides push notifications that can be consumed in
 the form of DOM events in the browser. Refer to the `W3C eventsource
-specification`_ for further details. CouchDB also honors the ``Last-Event-ID``
+specification`_ for further details. CouchDB also honours the ``Last-Event-ID``
 parameter.
 
 .. code-block:: text
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index a131e39b1..5265919b9 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -381,11 +381,11 @@ respond with a HTTP :http:statuscode:`202` response code immediately.
 
 .. note::
 
-   Creating or updating documents with batch mode doesn't guarantee that
-   document will be successfully stored on disk and CouchDB does not
-   guarantee that. For example, individual documents may not be saved due to
-   conflicts, rejection by :ref:`validation function <vdufun>` or by other
-   reasons, even if overall the batch transfer was sucessfully submitted.
+   Creating or updating documents with batch mode doesn't guarantee that all
+   documents will be successfully stored on disk. For example, individual
+   documents may not be saved due to conflicts, rejection by
+   :ref:`validation function <vdufun>` or by other reasons, even if overall
+   the batch was sucessfully submitted.
 
 **Request**:
 
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index 81935db2a..f7289e580 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -88,9 +88,10 @@
 .. http:post:: /{db}/_compact/{ddoc}
 
   Compacts the view indexes associated with the specified design document.
-  You can use this in place of the full database compaction if you know a
-  specific set of view indexes have been affected by a recent database
-  change.
+  If may be that compacting a large view can return more storage than
+  compacting the atual db. Thus, you can use this in place of the full
+  database compaction if you know a specific set of view indexes have been
+  affected by a recent database change.
 
   :param db: Database name
   :param ddoc: Design document name
@@ -144,7 +145,11 @@
 .. http:post:: /{db}/_ensure_full_commit
 
   Commits any recent changes to the specified database to disk. You should
-  call this if you want to ensure that recent changes have been written.
+  call this if you want to ensure that recent changes have been flushed.
+  This function is likely not required, assuming you have the recommended
+  configuration setting of ``delayed_commits=false``, which requires CouchDB
+  to ensure changes are written to disk before a 200 or similar result is
+  returned.
 
   :param db: Database name
   :<header Accept: - :mimetype:`application/json`