Apply Dachary feedback

source/sdk/kotlin/sync/add-sync-to-app.txt

@@ -15,78 +15,32 @@ Add Device Sync to an App - Kotlin SDK
 This page contains information about Device Sync, its basic concepts, 
 and how to add Sync to a client app with the Realm Kotlin SDK. 
 Once you have added Sync to your app, you can access a synced realm 
-from the client. Refer to :ref:`<kotlin-open-a-synced-realm>` for 
-more information.
+from the client. 
 
-For a detailed explanation of Device Sync, refer to 
-:ref:`realm-sync-get-started` in the Atlas App Services
-documentation.
 Already familiar with Device Sync? Skip ahead to the 
 :ref:`<kotlin-enable-sync-in-app-services>` section 
 to get started.
 
-.. note:: Flexible Sync Mode 
-
-   This page describes how to add Device Sync with Flexible Sync Mode. 
-   If your App Services backend uses the older Partition-Based Sync, refer to 
-   :ref:`kotlin-partition-based-sync`.
-
-   We recommend that you use Flexible Sync.
-
-.. _kotlin-add-sync-to-app-prereqs:
-
-Prerequisites
--------------
-
-You can add Device Sync to an app in several ways, depending on the state 
-of your app and your data. This guide describes how to add Sync to an 
-existing client app using Development Mode. This guide assumes that your 
-app uses the Realm Kotlin SDK and that you have already defined a data model. 
-
-Because Device Sync connects your client app to the App Services backend 
-through an Atlas App Services App, you need to following before you 
-can get started: 
-
-#. An Atlas App Services App with authentication enabled. To learn how, refer to :ref:`<create-a-realm-app>` in the App Services documentation.
-#. Confirm that your app can connect to the App Services backend. To learn how, refer to :ref:`<kotlin-connect-to-backend>`.
-
-.. _kotlin-example-sync-data-model:
-
-About the Examples on this Page
--------------------------------
-
-The examples on this page refer to an example Kotlin Todo app with an 
-already defined data model that includes a ``List`` object containing 
-a list of ``Item`` objects:
-
-.. literalinclude:: /examples/generated/kotlin/SchemaSync.snippet.sync-to-do-model.kt
-   :language: kotlin
-   :caption: Example ToDo app data model
-
-.. _kotlin-realm-sync:
-.. _kotlin-flexible-sync-fundamentals:
 
 Device Sync
 -----------
 
-**Device Sync** is an Atlas App Services feature that automatically 
-synchronizes data between client applications using a Realm SDK and
-an Atlas App Services backend linked to a MongoDB Atlas cluster. 
-When a client device is online, Sync uploads and downloads changesets 
-asynchronously in a background thread between the device and your 
-backend Atlas App.
+**Device Sync** synchronizes data between client devices and Atlas. 
+Data is persisted on a device, even when offline. When the device has a 
+network connection, Device Sync uploads and downloads
+data in the background and manages conflict resolution. 
 
-The data that syncs between your client app and the App 
-Services backend is determined by a user's permissions to eligible data. 
+The data that syncs between your client app and Atlas is determined by 
+a user's permissions to access eligible data. 
 
-Eligible data is determined by the following:
+- Data model: your data type information
+- Subscription queries: the conditions that define what data to store
+- Permissions: the role-based permissions required to interact with data 
+  that meets the specified conditions
 
-- Your Device Sync data model: The objects you want to sync.
-- Your subscription queries: The one or more client-side queries to those objects that specify the eligible data.
-
-The role-based permissions that you define in App Services control whether 
-that eligible data successfully syncs *to* or *from* the backend for an
-authorized user.
+For a detailed explanation of Device Sync, refer to 
+:ref:`realm-sync-get-started` in the Atlas App Services
+documentation.
 
 Data Model 
 ~~~~~~~~~~
@@ -104,14 +58,15 @@ Both schemas must be consistent with each other to sync data.
 You can define the Device Sync data model in a client app first or 
 in Atlas first:
 
-- To define your data mode through your client app, you first
+- To define your data model through your client app, you first
   :ref:`define an object model <kotlin-define-object-model>` 
   directly in your client app code. Then, you can use **Development Mode** to 
   generate a matching App Services schema automatically. Development Mode
   is a configuration setting that allows Device Sync 
   to infer and update schemas based on client-side data models when you 
-  sync data from the client. To learn more, refer to :ref:`<development-mode>` 
-  in the App Services documentation.
+  sync data from the client. The :ref:`<kotlin-enable-sync-in-app-services>` 
+  section describes how to enable Device Sync with Development Mode in your 
+  client app. 
 
 - If you already have data in Atlas and would
   prefer to define your data model through Atlas first, refer to 
@@ -122,13 +77,13 @@ Subscriptions
 
 A **subscription** is a client-side query to objects in your data model. 
 App Services only syncs objects that match the query. You can define multiple
-queries in your client app, but you can only query objects in your 
-data model. 
+queries in your client app. You must define at least one query for 
+each object type in your data model.
 
 App Services ensures that your client-side queries are consistent with
 your App Services schema through **queryable fields**. These are the 
 fields from your data model that can be used in a subscription query. You 
-cannot subscribe to a query that contains a non-queryable field.
+cannot define a subscription using a field that isn't in your queryable fields.
 When Development Mode is enabled, App Services automatically
 adds the fields that appear in your client queries as queryable fields.
 You can also manually add and remove queryable fields through the 
@@ -137,26 +92,62 @@ in the App Services documentation.
 
 For our example app, our data model contains an ``Item`` object 
 with a ``complete`` field. When Development Mode is enabled and we define a 
-subscription to query only incomplete items, then App Services would 
-automatically add ``complete`` as a queryable field when we sync the data.
+subscription to query only incomplete items, App Services 
+automatically adds ``complete`` as a queryable field when we sync the data.
 
 User Permissions
 ~~~~~~~~~~~~~~~~
 
-App Services uses **role-based permissions** to control what individual
-users can and cannot do with your app's data when they have a network 
-connection: 
+App Services uses **role-based permissions** to control the data that users 
+can read and write: 
 
-- When a user has read permissions, Atlas automatically syncs eligible 
-  data to the client.
-- When a user write permissions, Atlas automatically syncs any local changes 
-  to eligible data to the backend.
+- When a user has read permissions, Device Sync downloads data matching the
+  subscription query to the client.
+- When a user has write permissions, Atlas permits writes to the synced data 
+  and uploads locally-written data to the backend.
 
 You can define and manage roles in the App Services UI. When you enable Sync, 
 you select a default role, which you can modify later. For more information,
 refer to :ref:`<flexible-sync-roles>` in the App Services 
 documentation.
 
+.. _kotlin-add-sync-to-app-prereqs:
+
+Prerequisites
+-------------
+
+You can add Device Sync to an app in several ways, depending on the state 
+of your app and your data. This guide describes how to add Sync to an 
+existing client app using Development Mode. This guide assumes that your 
+app uses the Realm Kotlin SDK and that you have already defined a data model
+in your client code. 
+
+Because Device Sync connects your client app to the App Services backend 
+through an Atlas App Services App, you need to following before you 
+can get started: 
+
+#. An Atlas App Services App with authentication enabled. To learn how, 
+   refer to :ref:`<create-a-realm-app>` in the App Services documentation.
+#. Confirm that your app can connect to the App Services backend. 
+   To learn how, refer to :ref:`<kotlin-connect-to-backend>`.
+
+.. _kotlin-example-sync-data-model:
+
+About the Examples on this Page
+-------------------------------
+
+The examples on this page refer to an example Kotlin Todo app with an 
+already-defined data model that includes a ``List`` object containing 
+a list of ``Item`` objects:
+
+.. literalinclude:: /examples/generated/kotlin/SchemaSync.snippet.sync-to-do-model.kt
+   :language: kotlin
+   :caption: Example ToDo app data model
+
+.. _kotlin-realm-sync:
+.. _kotlin-flexible-sync-fundamentals:
+
+
 .. _kotlin-enable-sync-in-app-services:
 
 Enable Device Sync in App Services
@@ -185,8 +176,8 @@ documentation.
 For our example app, we enable Device Sync with Development Mode, and 
 then add the default "User can read and write all data 
 default" role. This means that, for an authorized user with a network 
-connection, Atlas will sync eligible data from Atlas to the client 
-*and* from the client to write to the backend. 
+connection, Device Sync downloads eligible data to the client 
+*and* Atlas permits writes to the client and then syncs them the backend. 
 
 Add Sync to Your Client App
 ---------------------------
@@ -219,7 +210,7 @@ you can add Sync to your client app.
 
    .. step:: Authenticate a User
 
-      Authenticate a user in your client app with a supported 
+      Authenticate a user in your client app using an 
       authentication provider that you have enabled. 
 
       For our example app, we log in a user using anonymous authentication: 
@@ -234,7 +225,7 @@ you can add Sync to your client app.
 
       Device Sync requires a `SyncConfiguration 
       <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.sync/-sync-configuration/index.html>`__
-      configuration object to open a synced realm. Note that 
+      object to open a synced realm. Note that 
       this is different than the ``RealmConfiguration`` object
       used to open a non-synced realm.
 
@@ -265,7 +256,7 @@ you can add Sync to your client app.
          The Sync configuration schema *must* include all object types that
          you want to work with in your synced realm. If you try to reference 
          or write an object of an object type that isn't in your schema, 
-         Realm will return a schema validation error.
+         Realm returns a schema validation error.
 
    .. step:: Open the Synced Realm
 
@@ -295,34 +286,49 @@ you can add Sync to your client app.
 Use the Realm
 -------------
 
-Now that you've open the configured synced realm, you can use it exactly 
-like a non-synced realm. The syntax to :ref:`read <kotlin-read-objects>`, 
+Now that you've open the configured synced realm, you can work with your 
+data in the realm. While you work with local data, a 
+background thread efficiently integrates, uploads, and downloads changesets. 
+
+The syntax to :ref:`read <kotlin-read-objects>`, 
 :ref:`write <kotlin-create-a-new-object>`, and
 :ref:`watch for changes <kotlin-react-to-changes>` is identical to the 
-syntax for non-synced realms. While you work with local data, a 
-background thread efficiently integrates, uploads, and downloads changesets. 
+syntax for non-synced realms. However, there are additional considerations when 
+writing data to a synced realm. For more information, refer to 
+:ref:`<kotlin-write-synced-realm>`.
 
 For our example app, we write a new ``List`` and ``Item`` object, 
 then copy them to the synced realm:
 
 .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.write-to-synced-realm.kt
    :language: kotlin
 
-The objects successfully sync to Atlas because: 
+The objects successfully write to the device, then sync to Atlas because: 
 
 - Both objects are within the parameters of the subscription query 
   (the ``List`` is owned by the user and the ``Item`` is incomplete). 
 - The current user has permission to write data to the backend (the role allows 
   authorized users to read and write all data).
 
+If our write operation didn't match the query *or* the current user didn't 
+have the requisite permissions, then Realm 
+reverts the write with a non-fatal error operation called a 
+:ref:`compensating write <kotlin-compensating-writes>`.
+
 Next Steps
 ----------
 
-Once your App is successfully syncing the desired data to Atlas, you 
+Once your app is successfully syncing the desired data to Atlas, you 
 can learn more about how to use Sync with the Kotlin SDK:
 
-- :ref:`<kotlin-open-a-synced-realm>`
-- :ref:`<kotlin-subscriptions>`
-- :ref:`<kotlin-write-synced-realm>`
-- :ref:`<kotlin-manage-sync-session>`
-- :ref:`<kotlin-handle-sync-errors>`
+- :ref:`<kotlin-open-a-synced-realm>`: Learn about the available 
+  configuration options, including how to open a synced realm offline.
+- :ref:`<kotlin-subscriptions>`: Learn how to define and manage 
+  the subscription queries in your app. 
+- :ref:`<kotlin-write-synced-realm>`: Learn more about how to write to
+  a synced realm, how to deal with compensating write errors, and how to 
+  group writes for improved performance.
+- :ref:`<kotlin-manage-sync-session>`: Learn how to manage 
+  communication with App Services through sync sessions.
+- :ref:`<kotlin-handle-sync-errors>`: Learn how to handle sync
+  errors that can occur, including client resets.