(DOCSP-12499) documents are now updated not replaced, when modified (#319)

* (DOCSP-12499) documents are now updated not replaced, when modified

* Included tech review and implemented includes

Author: JuliaMongo

source/documents/modify.txt

@@ -6,10 +6,12 @@ Modify Documents
 
 .. default-domain:: mongodb
 
-You can edit existing documents in your collection. When you edit
-a document, |compass-short| performs a
-:manual:`findAndModify </reference/method/db.collection.findAndModify/>`
-operation to update the document.
+You can edit existing documents in your collection.
+
+.. include:: /includes/fact-modify-findOneAndUpdate.rst
+
+.. include:: /includes/fact-modify-findOneAndReplace.rst
+
 
 Limitations
 -----------
@@ -36,7 +38,6 @@ documents in List, JSON, or Table view:
    :figwidth: 620px
    :alt: Document View Selection
 
-|
 
 .. tabs::
 
@@ -47,68 +48,77 @@ documents in List, JSON, or Table view:
       icon:
 
       .. figure:: /images/compass/edit-doc.png
-        :figwidth: 696px
+         :figwidth: 696px
+         :alt: Document Edit Selection
 
       After you click the pencil icon, the document enters edit mode:
 
       .. figure:: /images/compass/edit-doc2.png
-        :figwidth: 696px
+         :figwidth: 696px
+         :alt: Document Edit Mode
 
       You can now make changes to the fields, values, or data types
       of values.
 
       Delete Fields
-      -------------
+      ~~~~~~~~~~~~~
 
       To delete a field from a document, click the ``x`` icon to the
       left of the field:
 
       .. figure:: /images/compass/edit-doc3.png
-        :figwidth: 740px
+         :figwidth: 740px
+         :alt: Document Deletion
 
       Once selected, the field is marked for removal and appears
       highlighted in red:
 
       .. figure:: /images/compass/edit-doc4.png
-        :figwidth: 740px
+         :figwidth: 740px
+         :alt: Document Removal View
 
       Add New Fields
-      --------------
+      ~~~~~~~~~~~~~~
 
-      To add a new field in the document, hover over the row number in
-      the dialog (the row number is not part of the document but the
-      dialog display) and click on the plus sign add a new field after
-      the field.
+      To add a new field in the document after an existing field, hover
+      over the row number in the dialog and click on the plus sign. The
+      row number is not part of the document but is part of the dialog display.
 
       You can also add a new field at the end of the document by
       pressing the tab key when your text cursor is in the value of the
       last document field.
 
       Modify an Existing Field
-      ------------------------
+      ~~~~~~~~~~~~~~~~~~~~~~~~
 
-      You can modify documents by clicking on existing field names or
-      values and making changes. In this example, the flight status was
+      To modify documents, click on existing field names or
+      values and make changes. In this example, the flight status was
       changed from ``L`` to ``M``. Changed fields appear highlighted in
       yellow:
 
       .. figure:: /images/compass/update-field.png
-        :figwidth: 740px
+         :figwidth: 740px
+         :alt: Document Update View
+
+      .. include:: /includes/fact-modify-findOneAndUpdate.rst
+
+      .. include:: /includes/fact-modify-prevent-overwrites.rst
 
       Save Changes
-      ------------
+      ~~~~~~~~~~~~
 
       When you are finished editing the document, click the ``Update``
       button to commit your changes.
 
       Revert a Change
-      ---------------
+      ~~~~~~~~~~~~~~~
 
       To revert changes to a document, hover over the edited field
       and click the :guilabel:`revert icon` which appears to the left
       of the field's line number.
 
       .. figure:: /images/compass/revert-doc-list-view.png
+         :alt: Revert Document in List View
 
    .. tab:: JSON View
       :tabid: json
@@ -121,13 +131,14 @@ documents in List, JSON, or Table view:
       icon:
 
       .. figure:: /images/compass/document-edit-json.png
-        :figwidth: 696px
+         :figwidth: 696px
+         :alt: Document Edit Selection in JSON View
 
       After you click the pencil icon, the document enters edit mode.
       You can now add, remove, and edit field values by modifying
       the JSON document.
 
-      By default, embedded objects and arrays are hidden. To expand
+      By default, this view hides embedded objects and arrays. To expand
       embedded objects and array elements, hover over the target
       document and click the top arrow on the left side of the document.
 
@@ -136,7 +147,11 @@ documents in List, JSON, or Table view:
 
       .. figure:: /images/compass/expand-doc-json-view.png
          :figwidth: 696px
-         :alt: Expand embedded objects JSON
+         :alt: Expand embedded objects in JSON view
+
+      .. include:: /includes/fact-modify-findOneAndReplace.rst
+
+      .. include:: /includes/fact-modify-prevent-overwrites.rst
 
    .. tab:: Table View
       :tabid: table-view
@@ -146,14 +161,20 @@ documents in List, JSON, or Table view:
 
       .. figure:: /images/compass/table-view-modify.png
          :figwidth: 696px
+         :alt: Document Edit Selection in Table View
 
       After you click the pencil icon, the document enters edit mode:
 
       .. figure:: /images/compass/document-edit-table.png
-        :figwidth: 696px
+         :figwidth: 696px
+         :alt: Document Edit Mode in Table View
+
+      .. include:: /includes/fact-modify-findOneAndUpdate.rst
+      
+      .. include:: /includes/fact-modify-prevent-overwrites.rst
 
       Delete Fields
-      -------------
+      ~~~~~~~~~~~~~
 
       To delete a field from a document:
 
@@ -164,7 +185,7 @@ documents in List, JSON, or Table view:
       #. Click :guilabel:`Update` to confirm your changes.
 
       Add New Fields
-      --------------
+      ~~~~~~~~~~~~~~
 
       To add a new field to the document:
 
@@ -179,7 +200,7 @@ documents in List, JSON, or Table view:
       #. Click :guilabel:`Update` to confirm your changes.
 
       Revert a Change
-      ---------------
+      ~~~~~~~~~~~~~~~
 
       While modifying a document, you have the option to revert changes
       made to a field prior to saving the modified document.
@@ -188,6 +209,7 @@ documents in List, JSON, or Table view:
       right side of the edited table element.
 
       .. figure:: /images/compass/revert-doc-table-view.png
+         :alt: Document Revert Changes in Table View
 
 Cancel Changes
 --------------

source/includes/fact-modify-findOneAndReplace.rst

@@ -0,0 +1,3 @@
+When you edit a document in JSON view, |compass-short| performs a
+:manual:`findOneAndReplace </reference/method/db.collection.findOneAndReplace/>`
+operation and replaces the document.

source/includes/fact-modify-findOneAndUpdate.rst

@@ -0,0 +1,4 @@
+When you edit a document in List or Table view, |compass-short| performs a
+:manual:`findOneAndUpdate </reference/method/db.collection.findOneAndUpdate/>`
+operation and updates only those fields that you have
+changed.

source/includes/fact-modify-prevent-overwrites.rst

@@ -0,0 +1,5 @@
+If |compass-short| detects that you have changed fields
+that were modified outside of |compass-short|, it notifies you, preventing
+you from accidentally overwriting the changes made outside of |compass-short|.
+You can choose to proceed and replace the document by clicking :guilabel:`Update`,
+or cancel your changes.