DOCS-617 minor edits so UD docs are consistent with CR docs

draft/applications/delete.txt

@@ -5,14 +5,18 @@ Delete
 .. default-domain:: mongodb
 
 Of the four basic database operations (i.e. CRUD), *delete* operations
-are those that remove documents from a :term:`collection` in
-MongoDB. The :ref:`remove() <crud-delete-remove>` method in the
-:program:`mongo` shell provides this operation, as do corresponding
-methods in the :doc:`drivers </applications/drivers>`.
+are those that remove documents from a :term:`collection` in MongoDB.
 
-For more information about document removal and other write operations
-see :ref:`/core/write-operations`, for documentation of other basic
-database operations see the :doc:`/crud` page.
+For general information about write operations and the factors that affect
+their performance, see :ref:`/core/write-operations`; for documentation
+of other CRUD operations, see the :doc:`/crud` page.
+
+Overview
+--------
+
+The :ref:`remove() <crud-delete-remove>` method in the :program:`mongo`
+shell provides this operation, as do corresponding methods in the
+:doc:`drivers </applications/drivers>`.
 
 .. note::
 
@@ -31,22 +35,21 @@ the following prototype operation:
 
    db.collection.delete( <query>, <justOne>)
 
-In the :method:`remove() <db.collection.remove()>` consider the
-following rough analogies to SQL:
+.. admonition:: Corresponding operation in SQL
 
-- :method:`remove() <db.collection.remove()>` has the same function as
-  the ``DELETE`` statement,
+   The :method:`remove() <db.collection.remove()>` method is analogous to
+   the ``DELETE`` statement, and:
 
-- the ``<query>`` argument corresponds to the ``WHERE`` statement, and
+   - the ``<query>`` argument corresponds to the ``WHERE`` statement, and
 
-- the ``<justOne>`` argument has the same affect as ``LIMIT 1``.
+   - the ``<justOne>`` argument has the same affect as ``LIMIT 1``.
 
 Consider the following examples that illustrate the use of the
 :method:`remove() <db.collection.remove()>`:
 
-- If there is a query argument, the :method:`remove()
+- If there is a ``<query>`` argument, the :method:`remove()
   <db.collection.remove()>` method deletes from the collection all
-  documents that match the query.
+  documents that match the argument.
 
   The following operation deletes all documents from the ``csbios``
   collection where the ``first`` field in the subdocument ``name``
@@ -56,7 +59,7 @@ Consider the following examples that illustrate the use of the
 
      db.csbios.remove( { 'name.first' : /^G/ } )
 
-- If there is a query argument and you specify the ``justOne``
+- If there is a ``<query>`` argument and you specify the ``<justOne>``
   argument, :method:`remove() <db.collection.remove()>` only deletes a
   single documents from the collection that matches the query.
 
@@ -67,7 +70,7 @@ Consider the following examples that illustrate the use of the
 
      db.csbios.remove( { turing: true }, 1 )
 
-- If there is no ``query`` argument, the :method:`remove()
+- If there is no ``<query>`` argument, the :method:`remove()
   <db.collection.remove()>` method deletes all documents from a
   collection. The following operation deletes all documents from the
   ``csbios`` collection:
@@ -94,15 +97,15 @@ Capped Collection
 Isolation
 ~~~~~~~~~
 
-If the query argument to the :method:`remove()
+If the ``<query>`` argument to the :method:`remove()
 <db.collection.remove()>` method matches multiple documents in the
 collection, the delete operation may interleave with other write
 operations to that collection. For an unsharded collection, you have
 the option to override this behavior with the :operator:`$atomic`
 isolation operator, effectively isolating the delete operation and
-blocking all other operations during the delete operation. To isolate the operation,
-include ``$atomic: 1`` in the ``query`` parameter as in the following
-example:
+blocking all other operations during the delete operation. To isolate
+the operation, include ``$atomic: 1`` in the ``<query>`` parameter as in
+the following example:
 
 .. code-block:: javascript
 

draft/applications/update.txt

@@ -6,10 +6,13 @@ Update
 
 Of the four basic database operations (i.e. CRUD), *update* operations
 are those that modify existing records or :term:`documents <document>`
-in a MongoDB :term:`collection`. For more information about document
-modification and other write operations see :ref:`/core/write-operations`,
-for documentation of other basic database operations see the
-:doc:`/crud` page.
+in a MongoDB :term:`collection`. For general information about write
+operations and the factors that affect their performance, see
+:ref:`/core/write-operations`; for documentation of other CRUD
+operations, see the :doc:`/crud` page.
+
+Overview
+--------
 
 Update operation modifies an existing :term:`document <document>` or
 documents in a :term:`collection`. MongoDB provides the following
@@ -47,12 +50,18 @@ syntax:
 
    db.collection.update( <query>, <update>, <options> )
 
-The :method:`update() <db.collection.update()>` method corresponds to
-the ``UPDATE`` operation in SQL, while ``<query>`` argument
-corresponds to the ``WHERE`` statement and ``<update>`` corresponds to
-the ``SET ...`` statement. However, :method:`update()
-<db.collection.update()>` is more flexible and offers more control
-than the SQL equivalents.
+.. admonition:: Corresponding operation in SQL
+
+   The :method:`update() <db.collection.update()>` method corresponds
+   to the ``UPDATE`` operation in SQL, and:
+
+   - the ``<query>`` argument corresponds to the ``WHERE`` statement,
+     and
+
+   - the ``<update>`` corresponds to the ``SET ...`` statement.
+
+   However, :method:`update() <db.collection.update()>` is more
+   flexible and offers more control than its SQL equivalents.
 
 Consider the following examples that illustrate the use of the
 :method:`update() <db.collection.update()>` method:
@@ -76,7 +85,7 @@ Consider the following examples that illustrate the use of the
                                             by: 'IBM' } }
                        } )
 
-- If the update argument contains :operator:`$unset` operator, the
+- If the ``<update>`` argument contains :operator:`$unset` operator, the
   :method:`update() <db.collection.update()>` method removes the field
   from the document.
 
@@ -112,7 +121,7 @@ Consider the following examples that illustrate the use of the
   The following operation queries the ``csbios`` collection for the
   first document that has a ``name`` field equal to ``{ first: 'John',
   last: 'McCarthy' }`` and replaces all but the ``_id`` field in the
-  document with the fields in the ``update`` argument:
+  document with the fields in the ``<update>`` argument:
 
   .. code-block:: javascript
 
@@ -186,7 +195,7 @@ Consider the following examples that illustrate the use of the
        db.csbios.update( { _id: 6, 'awards.by': 'ACM'  } ,
                          { $set: { 'awards.$.by': 'Association for Computing Machinery' } } )
 
-- If the ``options`` argument contains the ``multi`` option set to
+- If the ``<options>`` argument contains the ``multi`` option set to
   ``true`` or ``1``, the :method:`update() <db.collection.update()>`
   method updates all documents that match the query.
 
@@ -201,19 +210,20 @@ Consider the following examples that illustrate the use of the
                        { $set: { turing: true } },
                        { multi: true } )
 
-- If you set the ``upsert`` option in the ``options`` argument, to
+- If you set the ``upsert`` option in the ``<options>`` argument to
   ``true`` or ``1`` and no existing document match the ``<query>``
   argument, the :method:`update() <db.collection.update()>` method can
   insert a new document into the collection:
 
   The following operation queries the ``csbios`` collection for a
   document with the ``_id`` field equal to ``11`` and the ``name``
   field equal to ``{ first: 'James', last: 'Gosling'}``. If the query
-  selects a document, the operation performs an update operation. If a document
-  is not found, :method:`update() <db.collection.update()>`  performs an insert operation of a new
-  document with the fields and values in the ``update`` argument and
-  the ``<query>`` argument since the ``update`` argument contains only
-  :ref:`update operators <update-operators>` expressions.
+  selects a document, the operation performs an update operation. If a
+  document is not found, :method:`update() <db.collection.update()>`
+  performs an insert operation of a new document with the fields and
+  values in the ``<update>`` argument and the ``<query>`` argument
+  since the ``<update>`` argument contains only :ref:`update operators
+  <update-operators>` expressions.
 
   .. code-block::javascript
 
@@ -247,7 +257,7 @@ The :method:`save() <db.collection.save()>` method updates an existing
 document or inserts a document depending on the ``_id`` field of the
 document. The :method:`save() <db.collection.save()>` method is
 analogous to the :method:`update() <db.collection.update()>` method
-with the ``upsert`` option and a ``query`` argument on the ``_id``
+with the ``upsert`` option and a ``<query>`` argument on the ``_id``
 field.
 
 The :method:`save() <db.collection.save()>` method has the
@@ -260,15 +270,15 @@ following syntax:
 Consider the following examples of the :method:`save()
 <db.collection.save()>` method:
 
-- If the ``document`` argument contains the ``_id`` field that exists
+- If the ``<document>`` argument contains the ``_id`` field that exists
   in the collection, the :method:`save() <db.collection.save()>` method
   performs an update that replaces the existing document with the
-  document argument.
+  ``<document>`` argument.
 
   The following operation queries the ``csbios`` collection for a
   document where the ``_id`` equals
   ``ObjectId("507c4e138fada716c89d0014")`` and replaces the document
-  with the ``document`` argument:
+  with the ``<document>`` argument:
 
   .. code-block:: javascript
 

draft/core/documents.txt

@@ -12,7 +12,7 @@ The document structure in MongoDB refer to the data structure of:
 - the :ref:`query selectors <documents-query-selectors>` that determine
   which records to select for read, update, and delete operations
 
-- the :ref:`update actions <documents-update-actions>` that specifies
+- the :ref:`update actions <documents-update-actions>` that specify
   the particular field updates to perform during an update operation
 
 - the :ref:`index <documents-index>` on a collection
@@ -41,7 +41,7 @@ structure:
    }
 
 Having support for the full range of :term:`BSON types`, MongoDB
-documents may contain ``field:value`` pairs where the value can be
+documents may contain ``field`` and ``value`` pairs where the value can be
 another document, an array, an array of documents as well
 as the basic types such as ``Double``, ``String``, or ``Date``.
 
@@ -99,7 +99,8 @@ Document as query selectors
 
 Query selector documents may contain any or all of the following:
 
-- Simple ``field:value`` pair(s) to specify the equality condition.
+- Simple ``field`` and ``value`` pair(s) to specify the equality
+  condition.
 
 - :doc:`Query operator </reference/operators>` expressions to specify
   other conditions.
@@ -191,7 +192,7 @@ When passed as an argument to the :method:`update()
 Document as index
 ----------------- 
 
-The index documents contain ``field:value`` pairs where: 
+The index documents contain ``field`` and ``value`` pairs where: 
 
 - the ``field`` is the field to index on
 
@@ -218,7 +219,7 @@ the index to create:
 Document as sort order
 ---------------------- 
 
-The sort order documents contain ``field:value`` pairs where: 
+The sort order documents contain ``field`` and ``value`` pairs where: 
 
 - the ``field`` is the field to sort
 

source/includes/fact-document-max-size.rst

@@ -1,7 +1,7 @@
 Documents have a 16 megabytes size limit.
 
 The maximum document size helps ensure that a single document cannot
-use neither an excessive amount of RAM nor excessive amount of
-bandwidth to transmit. To store larger objects, MongoDB provides the
+use excessive amount of RAM or, during transmission, excessive amount
+of bandwidth. To store larger objects, MongoDB provides the
 GridFS API to handle documents larger than the maximum size. See your
 specific driver documentation for GridFS.