moar updates

Author: tlrx

docs/java-rest/high-level/migration.asciidoc

@@ -22,11 +22,8 @@ https://www.elastic.co/blog/state-of-the-official-elasticsearch-java-clients[sta
 
 === Prerequisite
 
-The Java High Level Rest Client requires Java `1.8`. It can be used to send requests
-to an Elasticsearch cluster that is in version 5.6.0 or 6.0.0. When using the high-level
-client in version 5.x to talk to a cluster in version 6.0.0, breaking changes in the REST
-API may cause unexpected results and new APIs provided by Elasticsearch won't be known by
-the high-level client (but could be used with the Low-Level Rest Client).
+The Java High Level Rest Client requires Java `1.8` and can be used to send requests
+to an <<java-rest-high-compatibility,Elasticsearch cluster in a compatible version>>.
 
 === How to migrate
 
@@ -39,7 +36,7 @@ requires the following steps:
 
 === Updating the dependencies
 
-Java application that uses the `TransportClient` depend on the
+Java application that uses the `TransportClient` depends on the
 `org.elasticsearch.client:transport` artifact. This dependency
 must be replaced by a new dependency on the high-level client.
 
@@ -50,7 +47,7 @@ The <<java-rest-high-usage,Getting Started>> page shows
 
 === Changing the client's initialization code
 
-The `TransportClient` is typically initialized with something as follows:
+The `TransportClient` is typically initialized as follows:
 [source,java]
 --------------------------------------------------
 Settings settings = Settings.builder()
@@ -107,7 +104,7 @@ lowLevelRestClient.close();
 
 === Changing the application's code
 
-The `RestHighLevelClient` supports the same request and response object
+The `RestHighLevelClient` supports the same request and response objects
 as the `TransportClient`, but exposes slightly different methods to
 send the requests.
 

docs/java-rest/high-level/usage.asciidoc

@@ -4,6 +4,21 @@
 This section describes how to get started with the high-level REST client from
 getting the artifact to using it in an application.
 
+[[java-rest-high-compatibility]]
+=== Compatibility
+The Java High Level REST Client requires Java 1.8 and depends on the Elasticsearch
+core project. The client version is the same as the Elasticsearch version that the
+client was developed for. It accepts the same request arguments as the `TransportClient`
+and returns the same response objects.
+
+The High Level Client is backwards compatible but can only communicate with Elasticsearch
+version 5.5 and onwards. The High Level Client is forward compatible as well, meaning that
+it supports communicating with a later version of Elasticsearch than the one it was developed
+for. It is recommended to upgrade the High Level Client when upgrading the Elasticsearch
+cluster to a new major version, as REST API breaking changes may cause unexpected results,
+and newly added APIs will only be supported by the newer version of the client. The client
+should be updated last, once all of the nodes in the cluster have been upgraded.
+
 [[java-rest-high-javadoc]]
 === Javadoc