Merge branch 'next-datastore-docs' of https://github.com/aws-amplify/…

…docs into next-datastore-docs

docs/lib/datastore/conflict.md

@@ -3,11 +3,11 @@ title: Conflict resolution
 description: Learn more about how conflict resolution in DataStore is managed and how to configure it.
 ---
 
-When syncing with [AWS AppSync](https://aws.amazon.com/appsync/), DataStore updates from multiple clients will converge by tracking object versions and adhere to different conflict resolution strategies. The default strategy is called *"Auto Merge"* where GraphQL type information on an object is inspected at runtime to perform merge operations. You can read more about this behavior and alternatives such as *"Optimistic Concurrency"* control and *"Custom Lambda"* functions in the [AWS AppSync documentation](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html).
+If data synchronization is enabled via [AppSync](https://aws.amazon.com/appsync/), there can be different versions of the same object on the client and server. Multiple clients may have updated their respective copies of an object. DataStore will converge different object versions by applying conflict detection and resolution strategies. The default resolution is called *"Auto Merge"*. This strategy allows collections to grow, and prefers server-side versions of single-field data. Other strategies include *"Optimistic Concurrency"* control and *"Custom Lambda"* functions. For more information, see the [AWS AppSync documentation on conflict handling](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html).
 
 ## Custom conflict resolution
 
-To update the conflict resolution strategies navigate into your project from a terminal and run `amplify update api` choosing *Yes* when prompted to change the conflict detection and conflict resolution strategies:
+To select a different conflict resolution strategy, navigate into your project from a terminal and run `amplify update api`. Choose *Yes* when prompted to change the conflict detection and resolution strategies.
 
 ```console
 ? Please select from one of the below mentioned services: 

docs/lib/datastore/data-access.md

@@ -6,13 +6,13 @@ description: Learn how to save, query, paginate, update, delete and observe data
 
 ## Create and update
 
-To write data to the DataStore you can pass an instance of a model to `Amplify.DataStore.save()`.
+To write data to the DataStore, pass an instance of a model to `Amplify.DataStore.save()`:
 
 <inline-fragment platform="js" src="~/lib/datastore/fragments/js/data-access/save-snippet.md"></inline-fragment>
 <inline-fragment platform="ios" src="~/lib/datastore/fragments/ios/data-access/save-snippet.md"></inline-fragment>
 <inline-fragment platform="android" src="~/lib/datastore/fragments/android/data-access/save-snippet.md"></inline-fragment>
 
-The `save` method takes care of creating a new record or updating an existing one in case the model `id` already exists in the database.
+`save()` will create a new object, if the model's ID is not already known to the DataStore. Otherwise `save()` works like an update.
 
 <inline-fragment platform="js" src="~/lib/datastore/fragments/js/data-access/update-snippet.md"></inline-fragment>
 <inline-fragment platform="ios" src="~/lib/datastore/fragments/ios/data-access/update-snippet.md"></inline-fragment>
@@ -28,17 +28,17 @@ To delete an item simply pass in an instance.
 
 ## Query Data
 
-Querying data is always against the local database. When cloud synchronization is enabled, the local database is updated in the background by the DataStore Sync Engine.
+Queries are performed against the _local database_. When cloud synchronization is enabled, the local database is updated in the background by the DataStore Sync Engine.
 
-You can query using models as well as conditions using predicate filters to narrow down results.
+You can narrow the results of your query by specifying a model type of interest. For more advanced filtering, such as matching arbitrary field values on an object, you can supply a query predicate.
 
 <inline-fragment platform="js" src="~/lib/datastore/fragments/js/data-access/query-basic-snippet.md"></inline-fragment>
 <inline-fragment platform="ios" src="~/lib/datastore/fragments/ios/data-access/query-basic-snippet.md"></inline-fragment>
 <inline-fragment platform="android" src="~/lib/datastore/fragments/android/data-access/query-basic-snippet.md"></inline-fragment>
 
 ### Predicates
 
-You can apply predicate filters against the DataStore using the fields defined on your schema along with the following conditions.
+Predicates are filters that can be used to match items in the DataStore. When applied to a query(), they constrain the returned results. When applied to a save(), they act as a pre-requisite for updating the data. You can match against fields in your schema by using the following predicates:
 
 **Strings:** `eq | ne | le | lt | ge | gt | contains | notContains | beginsWith | between`