DOCSP-38601: Update Conflict Resolution with info on dictionary keys

source/sync/details/conflict-resolution.txt

@@ -4,8 +4,8 @@
 Conflict Resolution
 ===================
 
-.. meta:: 
-   :description: A high-level overview of how Atlas Device Sync resolves synced data conflicts.
+.. meta::
+   :description: Learn about how Atlas Device Sync automatically resolves synced data conflicts, or how to build custom conflict resolution rules.
 
 .. facet::
   :name: genre
@@ -17,9 +17,6 @@ Conflict Resolution
    :depth: 2
    :class: singlecol
 
-Overview
---------
-
 Conflicts arise when two or more users make changes to the same piece of
 data independently. This can happen due to latency between device and
 server or loss of connectivity. In this event, Atlas Device Sync automatically
@@ -28,14 +25,17 @@ Device Sync handles conflict resolution using `operational transformation
 <https://www.mongodb.com/docs/realm/sync/protocol/#operational-transformation>`__,
 a set of rules that guarantee strong eventual consistency, meaning all clients' versions
 will eventually converge to identical states. This will be true even if changes were
-made in a different order. 
-
+made in a different order.
 
 You must be aware of the rules to ensure consistent results, but the
 upside is that by following those rules, you can have devices work
 entirely offline and still converge on meaningful results when they
 meet.
 
+This page uses the example of a dog walking app to illustrate how Device Sync
+resolves conflicts. In this app, Matt and Sarah are both dog walkers who use
+the app to track their clients' dogs and their walking schedules.
+
 .. _rules-of-conflict-resolution:
 
 Rules of Conflict Resolution
@@ -61,12 +61,12 @@ Primary keys designate object identity.
   If two sides both create objects of the same class with identical
   primary keys, they will be treated as instances of the same object.
 
-.. example:: Conflict Resolution Example
+.. example:: Conflict Resolution Between Two Users
 
    Matt and Sarah are working on data for their dog walking business. Matt
    deletes data on one of their client's dogs, Doug, as they no longer need to walk him.
-   While Sarah is out without internet connection, she edits Doug's required walk time 
-   data on her local, offline version, as she does not know about Matt's deletion of Doug's data. 
+   While Sarah is out without internet connection, she edits Doug's required walk time
+   data on her local, offline version, as she does not know about Matt's deletion of Doug's data.
 
    Once Sarah regains internet connection, her change will be sent to the server. The server will
    send her Matt's deletion operation. As deletes always win according to Device Sync's
@@ -99,20 +99,20 @@ allowing you to get more precise control of the conflict resolution.
 Nested Collections
 ~~~~~~~~~~~~~~~~~~
 
-Nested collections are treated similarly to embedded objects. That is, 
-they are considered child objects with a specific parent object. Any updates to 
-the parent object will always win in a conflict resolution, even if it 
+Nested collections are treated similarly to embedded objects. That is,
+they are considered child objects with a specific parent object. Any updates to
+the parent object will always win in a conflict resolution, even if it
 overwrites the child object.
 
-Updates to a nested collection are resolved as follows: 
+Updates to a nested collection are resolved as follows:
 
 - If multiple devices *update* the same existing nested collection, Device Sync uses
   normal conflict resolution rules to incorporate both changes.
 
-- If multiple devices *create* new unique collections nested in the same 
+- If multiple devices *create* new unique collections nested in the same
   parent object, the "last update wins" rule applies, and Device Sync overwrites
-  all other updates with the last update made. 
-  
+  all other updates with the last update made.
+
 For example, client details in Sarah and Matt's dog walking app are modeled as
 arrays nested in the parent ``client`` property. Sarah - and then later, Matt -
 each create a new details collection for the same client on their
@@ -122,16 +122,30 @@ one made.
 
 Later, Sarah and Matt each make unique updates to the newly created details entry. Device Sync will merge these updates according to
 normal conflict resolution rules, inserting the new or modified items to the
-list in chronological order. 
+list in chronological order.
 
 Strings
 ~~~~~~~
 
 Device Sync interprets the value of a string as a whole and does not merge
-conflicts on a per-character basis. For example, this means that if a character 
+conflicts on a per-character basis. For example, this means that if a character
 or substring is inserted or deleted within a string, Device Sync will treat
 this as a replacement of the entire value of the string.
 
+Dictionaries
+~~~~~~~~~~~~
+
+Device Sync considers the removal of a dictionary key to be an update, rather
+than a deletion. As a result, the "Last update wins" rule is applied instead of
+the "Deletes always win" rule.
+
+For example, the dog walking app contains an optional collection of details for
+each dog, which are entered as key-values. While both users are offline, Sarah
+deletes the entire ``favorite toy`` entry for a dog, and later Matt updates the
+same dog's favorite toy to ``tennis ball``. When both come back online, Device
+Sync considers both as updates to the ``favorite toy`` entry and applies Matt's
+updates because he made them after Sarah's deletion.
+
 .. _custom-conflict-resolution:
 
 Custom Conflict Resolution
@@ -150,9 +164,9 @@ Summary
 -------
 
 - Device Sync implements a conflict resolution system to allow multiple offline writers to write simultaneously and still eventually converge on the same result.
-- The conflict resolution system follows four rules: 
-    - Deletes always win.
-    - The last update wins. 
-    - Inserts in lists are ordered by time.
-    - Primary keys designate object identity.
+- The conflict resolution system follows four rules:
+   - Deletes always win.
+   - The last update wins.
+   - Inserts in lists are ordered by time.
+   - Primary keys designate object identity.
 - Counters, nested collections, and strings are special cases to be aware of in your client code.