More changes to java update-by-query api docs

docs/java-api/docs/update-by-query.asciidoc

@@ -39,8 +39,8 @@ the conflicting document was updated between the start of the `updateByQuery`
 and the time when it attempted to update the document. This is fine because
 that update will have picked up the online mapping update.
 
-Back to the API, `UpdateByQueryRequestBuilder` supports filtering the documents
-that are updated, limiting the total number updated, and updating documents
+The `UpdateByQueryRequestBuilder` API supports filtering the updated documents,
+limiting the total number of documents to update, and updating documents
 with a script:
 
 [source,java]
@@ -55,8 +55,8 @@ updateByQuery.source("source_index")
 BulkIndexByScrollResponse response = updateByQuery.get();
 --------------------------------------------------
 
-`UpdateByQueryRequestBuilder` also allows you direct access to the query used
-to select the documents which you can use to change the default scroll size or
+`UpdateByQueryRequestBuilder` also enables direct access to the query used
+to select the documents. You can use this access to change the default scroll size or
 otherwise modify the request for matching documents.
 
 [source,java]
@@ -81,8 +81,8 @@ updateByQuery.source("source_index").size(100)
 BulkIndexByScrollResponse response = updateByQuery.get();
 --------------------------------------------------
 
-In addition to changing the `_source` of the document (see above) the script
-can change the update action similarly to the Update API:
+In addition to changing the `_source` field for the document, you can use a
+script to change the action, similar to the Update API:
 
 [source,java]
 --------------------------------------------------
@@ -100,14 +100,14 @@ updateByQuery.source("source_index")
 BulkIndexByScrollResponse response = updateByQuery.get();
 --------------------------------------------------
 
-Just as in <<docs-update,Update API>> you can set `ctx.op` to change the
-operation that is executed:
+As in the <<docs-update,Update API>>, you can set the value of `ctx.op` to change the
+operation that executes:
 
 `noop`::
 
-Set `ctx.op = "noop"` if your script decides that it doesn't have to make any
-changes. That will cause `updateByQuery` to omit that document from its updates.
- This no operation will be reported in the `noop` counter in the
+Set `ctx.op = "noop"` if your script doesn't make any
+changes. The `updateByQuery` operaton then omits that document from the updates.
+This behavior increments the `noop` counter in the
 <<docs-update-by-query-response-body, response body>>.
 
 `delete`::
@@ -116,15 +116,14 @@ Set `ctx.op = "delete"` if your script decides that the document must be
 deleted. The deletion will be reported in the `deleted` counter in the
 <<docs-update-by-query-response-body, response body>>.
 
-Setting `ctx.op` to anything else is an error. Setting any
-other field in `ctx` is an error.
+Setting `ctx.op` to any other value generates an error. Setting any
+other field in `ctx` generates an error.
 
 This API doesn't allow you to move the documents it touches, just modify their
 source. This is intentional! We've made no provisions for removing the document
 from its original location.
 
-It's also possible to do this whole thing on multiple indexes and multiple
-types at once, just like the search API:
+You can also perform these operations on multiple indices and types at once, similar to the search API:
 
 [source,java]
 --------------------------------------------------
@@ -135,7 +134,7 @@ updateByQuery.source("foo", "bar").source().setTypes("a", "b");
 BulkIndexByScrollResponse response = updateByQuery.get();
 --------------------------------------------------
 
-If you provide `routing` then the routing is copied to the scroll query,
+If you provide a `routing` value then the process copies the routing value to the scroll query,
 limiting the process to the shards that match that routing value:
 
 [source,java]
@@ -201,28 +200,26 @@ client.admin().cluster().prepareCancelTasks().setActions(UpdateByQueryAction.NAM
 client.admin().cluster().prepareCancelTasks().setTaskId(taskId).get().getTasks()
 --------------------------------------------------
 
-The `taskId` can be found using the list tasks API above.
-
-Cancelation should happen quickly but might take a few seconds. The task status
-API above will continue to list the task until it is wakes to cancel itself.
+Use the `list tasks` API to find the value of `taskId`.
 
+Cancelling a request is typically a very fast process but can take up to a few seconds.
+The task status API continues to list the task until the cancellation is complete.
 
 [float]
 [[docs-update-by-query-rethrottle]]
 === Rethrottling
 
-The value of `requests_per_second` can be changed on a running update by query
-using the `_rethrottle` API:
+Use the `_rethrottle` API to change the value of `requests_per_second` on a running update:
 
 [source,java]
 --------------------------------------------------
 RethrottleAction.INSTANCE.newRequestBuilder(client).setTaskId(taskId).setRequestsPerSecond(2.0f).get();
 --------------------------------------------------
 
-The `taskId` can be found using the tasks API above.
+Use the `list tasks` API to find the value of `taskId`.
 
-Just like when setting it on the `updateByQuery` API `requests_per_second`
-can be either `Float.POSITIVE_INFINITY` to disable throttling or any positive
-float to throttle to that level. Rethrottling that speeds up the query takes
-effect immediately but rethrotting that slows down the query will take effect
-on after completing the current batch. This prevents scroll timeouts.
+As with the `updateByQuery` API, the value of `requests_per_second`
+can be any positive float value to set the level of the throttle, or `Float.POSITIVE_INFINITY` to disable throttling.
+A value of `requests_per_second` that speeds up the process takes
+effect immediately. `requests_per_second` values that slow the query take effect
+after completing the current batch in order to prevent scroll timeouts.