More doc fixes

docs/api.rst

@@ -1,6 +1,14 @@
 API Documentation
 =================
 
+.. note::
+
+    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.
+
 .. py:module:: elasticsearch
 
 Elasticsearch

docs/connection.rst

@@ -1,3 +1,5 @@
+.. _connection_api:
+
 Connection Layer API
 ====================
 

docs/index.rst

@@ -49,6 +49,26 @@ Example Usage
     {u'text': u'Elasticsearch: cool. bonsai cool.', u'author': u'kimchy', u'timestamp': u'2010-10-10T10:10:10'}
     Got 1 Hits:
     2010-10-10T10:10:10 kimchy: Elasticsearch: cool. bonsai cool.
+
+Features
+--------
+
+Extendability
+~~~~~~~~~~~~~
+
+Configurable connections and load balancing (see :ref:`connection_api`)::
+ * persistent connections
+ * configurable load balancing strategy
+ * different protocols and connection classes
+ * ...
+
+
+Sniffing
+~~~~~~~~
+
+The client can be configured to inspect the cluster state to get a list of
+nodes upon startup, periodically and/or on failure. See
+:class:`~elasticsearch.Transport` parameters for details.
     
 Contents
 --------
@@ -58,6 +78,7 @@ Contents
 
    api
    connection
+   transports
 
 License
 -------