Merge pull request #185 from neo4j/nit-picky

Mutation pages updates

Author: rsill-neo4j

modules/ROOT/pages/mutations/create.adoc

@@ -2,7 +2,7 @@
 :description: This page describes how to create nodes through mutations.
 = `create`
 
-Using the following type definitions:
+Consider the following type definitions:
 
 [source, graphql, indent=0]
 ----
@@ -19,7 +19,7 @@ type User {
 }
 ----
 
-These `create` mutations and response types should be generated:
+The following `create` mutations and response types are generated:
 
 [source, graphql, indent=0]
 ----
@@ -65,11 +65,12 @@ mutation {
 }
 ----
 
-This should create a `User` with name "John Doe", and that name plus the autogenerated ID should be returned.
+This creates a `User` with the name "John Doe".
+The name and the autogenerated ID are returned.
 
 == Nested `create`
 
-A `User` and an initial `Post` can be created by executing the following:
+You can create a `User` and their initial `Post` at once by executing the following:
 
 [source, graphql, indent=0]
 ----
@@ -101,7 +102,7 @@ mutation {
 ----
 
 This creates a `User` with name "John Doe" and an introductory post.
-Both should be returned with their autogenerated IDs.
+Both are returned with their autogenerated IDs.
 
 [NOTE]
 ====
@@ -111,7 +112,7 @@ Read about xref:mutations/update.adoc#_connectorcreate_relationships[`update`] f
 
 == `connectOrCreate` relationships
 
-If a related node has the `@unique` directive defined, `connectOrCreate` can be used in a nested `create` to perform a `MERGE` operation on the related node.
+If a related node has the `@unique` directive defined, you can use `connectOrCreate` nested in a `CREATE` mutation to perform an operation similar to a link:https://neo4j.com/docs/cypher-manual/current/clauses/merge/[Cypher `MERGE`] operation on the related node.
 This will create a new relationship and the related node if it doesn't exist yet.
 
 Consider the following type definitions:
@@ -130,7 +131,7 @@ type Movie {
 }
 ----
 
-Because a movie ID is unique, `connectOrCreate` can be used in an `Actor` mutation to ensure the movie exists in the database before connecting. 
+Since a movie ID is unique, you can use `connectOrCreate` in an `Actor` mutation to ensure the movie exists in the database before connecting them.
 Note that only `@unique` or `@id` fields can be used in `where`:
 
 [source, graphql, indent=0]
@@ -152,15 +153,17 @@ mutation {
 }
 ----
 
-This will ensure that a movie with ID 1234 exists and it is connected to `"Tom Hanks"`. If the movie does not exist, it will be created with the title `"Forrest Gump"`. Note that if the movie with the given ID already exists, it will be connected to it, regardless of the title.
+This ensures that a movie with ID 1234 exists and is connected to `"Tom Hanks"`.
+If the movie does not exist, it will be created with the title `"Forrest Gump"`.
+If a movie with the given ID already exists, it will also be connected to `"Tom Hanks"`, and keep whatever title it has.
 
 == `CREATE` optimization
 
-With the `create` operations, there is no limit on how many nodes can be created at once.
+With `CREATE` operations, there is no limit on how many nodes can be created at once.
 However, there is a known performance issue for large batch sizes. 
 
 The Neo4j GraphQL Library contains an optimization feature designed to mitigate it, but it does not work in the following scenarios:
 
 * A field is populated using the directive `@populated_by`.
-* The `connect` or `connectOrCreate` operation is used.
+* The `connect` or `connectOrCreate` operations are used.
 * Interface and union types are present in the mutation.

modules/ROOT/pages/mutations/delete.adoc

@@ -4,7 +4,7 @@
 
 = `delete`
 
-Using these type definitions:
+Consider these type definitions:
 
 [source, graphql, indent=0]
 ----
@@ -21,7 +21,7 @@ type User {
 }
 ----
 
-These `delete` mutations and response types should be generated:
+The following `delete` mutations and response types are generated:
 
 [source, graphql, indent=0]
 ----
@@ -43,7 +43,7 @@ The `DeleteInfo` type is the common return type for all delete mutations.
 
 == Single `delete`
 
-A single post can be deleted by executing the following GraphQL statement:
+You can delete a single post by executing the following GraphQL statement:
 
 [source, graphql, indent=0]
 ----
@@ -57,12 +57,12 @@ mutation {
 }
 ----
 
-This should delete the post using the autogenerated ID that was returned after that post's creation.
-Consequently, `nodesDeleted` should be equal `1` (the post) and `relationshipsDeleted` should also equal `1` as the `HAS_POST` relationship between the `Post` and its author was deleted.
+This deletes the post using the autogenerated ID that was returned after the creation of the post.
+Consequently, `nodesDeleted` is equal to `1` (the post) and `relationshipsDeleted` is also equal to `1` as the `HAS_POST` relationship between the `Post` and its author was deleted.
 
 == Nested `delete`
 
-In case you want to delete a `User` *and* all of their posts, you can use a single nested `delete` mutation:
+In case you want to delete a `User` and all of their posts, you can use a single nested `delete` mutation:
 
 [source, graphql, indent=0]
 ----
@@ -74,8 +74,7 @@ mutation {
 }
 ----
 
-By the time the traversal has reached it, that empty `where` argument has the context of only refer to posts that were created by Jane Doe, as the traversals to those `Post` nodes were from her `User` node. 
-Essentially, the above query is equivalent to:
+This query is equivalent to:
 
 [source, graphql, indent=0]
 ----
@@ -104,10 +103,12 @@ mutation {
 
 Note that the output Cypher statement should also have a redundant `WHERE` clause:
 
+// !
 //Please add the cypher statement:
 
 //[source, cypher, indent=0]
 //----
 //DELETE User (name:"Jane Doe") 
 //WHERE Posts -
 //----
+// !

modules/ROOT/pages/mutations/index.adoc

@@ -3,7 +3,7 @@
 :description: This section describes how to use mutations with the Neo4j GraphQL Library.
 
 
-This section addresses basic examples of the following mutations:
+This page shows examples of the following mutations:
 
 - xref::mutations/create.adoc[`create`] - create nodes, and recursively create or connect further nodes in the graph.
 - xref::mutations/update.adoc[`update`] - update nodes, and recursively perform any operations from there.
@@ -15,5 +15,5 @@ In order to provide the abstractions available in these mutations, the output Cy
 This can result in your database throwing out-of-memory errors depending on its configuration.
 
 If this becomes a regular occurrence, you can adjust the link:https://neo4j.com/docs/operations-manual/current/configuration/configuration-settings/#config_server.memory.heap.max_size[`server.memory.heap.max_size`] parameter in the DBMS settings.
-If you need to perform major data migrations, it may be best to manually write the necessary Cypher and execute this directly in the database.
+If you must perform major data migrations, it may be best to manually write the necessary Cypher and execute this directly in the database.
 ====