Better phrasing of th compatibility warning. Thanks, karmi!

README.rst

@@ -5,21 +5,34 @@ 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.
 
-Versioning
+Compatibility
-----------
+-------------
 
-There are two branches for development - `master` and `0.4`. Master branch is
+The library is compatible with both Elasticsearch 1.x and 0.90.x but you
-used to track all the changes for Elasticsearch 1.0 and beyond whereas 0.4
+**have to use a matching version**.
-tracks Elasticsearch 0.90.
 
-Releases with major version 1 (1.X.Y) are to be used with Elasticsearch 1.0 and
+For **Elasticsearch 1.0** and later, use the major version 1 (``1.x.y``) of the
-later, 0.4 releases are meant to work with Elasticsearch 0.90.X.
+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.
 
 
 Installation
 ------------
 
-Install the `elasticsearch` package with `pip
+Install the ``elasticsearch`` package with `pip
 <https://pypi.python.org/pypi/elasticsearch>`_::
 
     pip install elasticsearch

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
+however, recommend that people **use keyword arguments for all calls for
-consistency and safety*.
+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
 -------------