More extensive README

README.rst

@@ -1,6 +1,50 @@
 Python Elasticsearch Client
 ===========================
 
+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.
+
+
+Example use
+-----------
+
+Simple use-case::
+
+    >>> from datetime import datetime
+    >>> from elasticsearch import Elasticsearch
+
+    # by default we connect to localhost:9200
+    >>> es = Elasticsearch()
+
+    # datetimes will be serialized
+    >>> es.index("my-index", "test-type", {"any": "data", "timestamp": datetime.now()}, id=42)
+    {u'_id': u'42', u'_index': u'my-index', u'_type': u'test-type', u'_version': 1, u'ok': True}
+
+    # but not deserialized
+    >>> es.get("my-index", 42, doc_type="test-type")['_source']
+    {u'any': u'data', u'timestamp': u'2013-05-12T19:45:31.804229'}
+
+
+Features
+--------
+
+The client's features include:
+
+ * translating basic Python data types to and from json (datetimes are not
+   decoded for performance reasons)
+ * configurable automatic discovery of cluster nodes
+ * persistent connections
+ * load balancing (with pluggable selection strategy) across all availible nodes
+ * failed connection penalization (time based - failed connections won't be
+   retried until a timeout is reached)
+ * thread safety
+ * pluggable architecture
+
+
+License
+-------
+
 Copyright 2013 Elasticsearch
 
 Licensed under the Apache License, Version 2.0 (the "License");