MW feedback

Author: mcmorisi

source/write/update.txt

@@ -29,7 +29,7 @@ Sample Data
 
 The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
 database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
-from your {+language+} application, create a ``Mongo::Client`` that connects to an Atlas cluster
+from your {+language+} application, create a ``Mongo::Client`` object that connects to an Atlas cluster
 and assign the following values to your ``database`` and ``collection`` variables:
 
 .. literalinclude:: /includes/write/update.rb
@@ -46,8 +46,8 @@ Update Operations
 
 You can update documents in MongoDB by using the following methods:
 
-- ``update_one``, which updates *the first document* that matches the search criteria
-- ``update_many``, which updates *all documents* that match the search criteria
+- ``update_one``: Updates *the first document* that matches the search criteria
+- ``update_many``: Updates *all documents* that match the search criteria
 
 Each update method requires the following parameters:
 
@@ -64,10 +64,9 @@ Each update method requires the following parameters:
 Update One Document Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following example uses the ``update_one`` method to update the
-``name`` field value of a document from ``"Happy Garden"`` to ``"Mountain
-House"``. The update document uses the ``$set`` operation to update the ``name`` field
-value:
+The following example uses the ``update_one`` method to find the first document
+where the value of the ``name`` field is ``"Happy Garden"``. It then uses the ``$set``
+operator to update the ``name`` field value to ``"Mountain House"``.
 
 .. io-code-block::
    :copyable: true
@@ -88,8 +87,8 @@ Update Many Documents Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following example uses the ``update_many`` method to update all documents
-in which the ``name`` field value is ``"Starbucks"``. The update document uses the
-``rename()`` method to change the name of the ``address`` field to ``location``:
+where the value of the ``name`` field is ``"Starbucks"``. The update document uses the
+``$rename`` operator to change the name of the ``address`` field to ``location``.
 
 .. io-code-block::
    :copyable: true
@@ -111,9 +110,9 @@ Customize the Update Operation
 
 The ``update_one`` and ``update_many`` methods accept options to configure the update
 operation. You can pass these options individually as parameters, or you can create a
-``Hash`` object that contains the options and pass it as a parameter.
-If you don't specify any options, the driver performs update
-operations with default settings.
+``Hash`` object that contains the options and pass the object as a parameter.
+If you don't specify any options, the driver performs the update
+operation with default settings.
 
 The following table describes the options that you can use to
 configure the update operation:
@@ -126,36 +125,36 @@ configure the update operation:
      - Description
 
    * - ``upsert``
-     - | Specifies whether the update operation performs an upsert operation if no 
+     - | Whether the update operation performs an upsert operation if no 
          documents match the query filter. For more information, see the :manual:`upsert
          statement </reference/command/update/#std-label-update-command-upsert>`
          in the {+mdb-server+} manual.
-       | Defaults to ``false``
+       | Default: ``false``
 
    * - ``bypass_document_validation``
-     - | Specifies whether the update operation bypasses document validation. This lets you 
+     - | Whether the update operation bypasses document validation. This lets you 
          update documents that don't meet the schema validation requirements, if any 
          exist. For more information about schema validation, see :manual:`Schema
          Validation </core/schema-validation/#schema-validation>` in the MongoDB
          Server manual.
-       | Defaults to ``false``.
+       | Default: ``false``
 
    * - ``collation``
-     - | Specifies the kind of language collation to use when sorting
+     - | The kind of language collation to use when sorting
          results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
          in the {+mdb-server+} manual.
 
    * - ``array_filters``
-     - | Provides a list of filters that you specify to select which
+     - | List of filters that you specify to select which
          array elements the update applies to.
 
    * - ``hint``
-     - | Sets the index to use when matching documents. 
+     - | Index to use when matching documents. 
          For more information, see the :manual:`hint statement </reference/command/update/#std-label-update-command-hint>`
          in the {+mdb-server+} manual.
 
    * - ``let``
-     - | Provides a map of parameter names and values to set top-level
+     - | A map of parameter names and values to set top-level
          variables for the operation. Values must be constant or closed
          expressions that don't reference document fields. For more information,
          see the :manual:`let statement
@@ -165,15 +164,14 @@ configure the update operation:
 Modify Update Example
 `````````````````````
 
-This example creates and passes options to the ``update_one`` method.
-The example uses the ``$equal`` operation to match documents
-in which the ``name`` field value is ``"Sunrise Pizzeria"``. It then uses the ``$set`` 
-operation to set the ``borough`` field value in the first matching document to
+The example uses the ``$equal`` operator to match documents
+where the value of the ``name`` field is ``"Sunrise Pizzeria"``. It then uses the ``$set`` 
+operator to set the ``borough`` field value in the first matching document to
 ``"Queens"`` and the ``cuisine`` field value to ``"Italian"``.
 
-Because the ``upsert`` option is set to ``true``, the driver inserts a new document that
-has the fields and values specified in the filter and update document if the query filter
-doesn't match any existing documents.
+Because the ``upsert`` option is set to ``true``, if the query filter
+doesn't match any existing documents, the driver inserts a new document that
+has the fields and values in the filter and update documents.
 
 .. io-code-block::
    :copyable: true
@@ -194,7 +192,7 @@ Return Value
 ~~~~~~~~~~~~
 
 The ``update_one`` and ``update_many`` methods each return a ``Result`` 
-object. You can use the access the following instance methods from a ``Result`` instance:
+object. You can access the following methods from a ``Result`` instance:
 
 .. list-table::
    :widths: 30 70
@@ -204,11 +202,11 @@ object. You can use the access the following instance methods from a ``Result``
      - Description
 
    * - ``matched_count``
-     - | Returns the number of documents that matched the query filter, regardless of
+     - | Number of documents that matched the query filter, regardless of
          how many updates were performed.
 
    * - ``modified_count``
-     - | Returns the number of documents modified by the update operation. If an updated
+     - | Number of documents modified by the update operation. If an updated
          document is identical to the original, it is not included in this
          count.
 
@@ -223,12 +221,13 @@ object. You can use the access the following instance methods from a ``Result``
      - | Returns the ``_id`` value of the document that was upserted
          in the database, if the driver performed an upsert.
 
-.. note::
+.. tip::
 
-   If the ``acknowledged?`` method returns ``false``, trying to
-   access other information from the ``Result`` instance results in an
-   ``InvalidOperation`` exception. The driver cannot 
-   determine these values if the server does not acknowledge the write
+   Check the value of the ``acknowledged?`` method before you try
+   to call any other ``Result`` methods. If the ``acknowledged?``
+   method returns ``false``, the driver throws an ``InvalidOperation``
+   exception if you try to call any other method on the ``Result`` object.
+   The driver cannot determine these values if the server does not acknowledge the write
    operation.
 
 Additional Information