Better phrasing of th compatibility warning. Thanks, karmi!

docs/api.rst

@@ -6,8 +6,8 @@ API Documentation
 All the API calls map the raw REST api as closely as possible, including the
 distinction between required and optional arguments to the calls. This means
 that the code makes distinction between positional and keyword arguments; we,
-however, recommend that people *use keyword arguments for all calls for
-consistency and safety*.
+however, recommend that people **use keyword arguments for all calls for
+consistency and safety**.
 
 An API call is considered successful (and will return a response) if
 elasticsearch returns a 2XX response. Otherwise an instance of

docs/index.rst

@@ -5,6 +5,28 @@ Official low-level client for Elasticsearch. It's goal is to provide common
 ground for all Elasticsearch-related code in Python; because of this it tries
 to be opinion-free and very extendable.
 
+Compatibility
+-------------
+
+The library is compatible with both Elasticsearch 1.x and 0.90.x but you
+**have to use a matching version**.
+
+For **Elasticsearch 1.0** and later, use the major version 1 (``1.x.y``) of the
+library.
+
+For **Elasticsearch 0.90.x**, use a version from ``0.4.x`` releases of the
+library.
+
+The recommended way to set your requirements in your `setup.py` or
+`requirements.txt` is::
+
+    # Elasticsearch 1.0
+    elasticsearch>=1.0.0,<2.0.0
+
+    # Elasticsearch 0.90
+    elasticsearch<1.0.0
+
+The development is happening on ``master`` and ``0.4`` branches, respectively.
 
 Example Usage
 -------------