Improved README

README.md

@@ -1,40 +1,94 @@
 Confluent's Apache Kafka client for Python
 ==========================================
 
+Confluent's Kafka client for Python wraps the librdkafka C library, providing
+full Kafka protocol support at great performance and reliability.
 
-Prerequisites
-===============
+The Python bindings provides a high-level Producer and Consumer with support
+for the balanced consumer groups of Apache Kafka 0.9.
 
-    librdkafka >=0.9.1 (or master>=2016-04-13)
-    py.test  (pip install pytest)
+See the [API documentation](http://docs.confluent.io/3.0.0/clients/confluent-kafka-python/index.html) for more info.
 
 
-Build
+Usage
 =====
 
-    python setup.by build
+**Producer:**
+
+    from confluent_kafka import Producer
+
+    p = Producer({'bootstrap.servers': 'mybroker,mybroker2'})
+    for data in some_data_source:
+        p.produce('mytopic', data.encode('utf-8'))
+    p.flush()
+
+
+**High-level Consumer:**
+
+    from confluent_kafka import Consumer
+
+    c = Consumer({'bootstrap.servers': 'mybroker', 'group.id': 'mygroup',
+                  'default.topic.config': {'auto.offset.reset': 'smallest'}})
+    c.subscribe(['mytopic'])
+    while running:
+        msg = c.poll()
+        if not msg.error():
+            print('Received message: %s' % msg.value().decode('utf-8'))
+    c.close()
+
+
+
+See [examples](examples) for more examples.
+
+
+
+Prerequisites
+=============
+
+ * Python >= 2.7 or Python 3.x
+ * [librdkafka](https://github.com/edenhill/librdkafka) >= 0.9.1
 
 
 
 Install
 =======
-Preferably in a virtualenv:
+
+**Install from PyPi:**
+
+    pip install confluent-kafka
+
+
+**Install from source / tarball:**
 
     pip install .
 
 
-Run unit-tests
-==============
+Build
+=====
+
+    python setup.by build
+
+
+
+
+Tests
+=====
+
+
+**Run unit-tests:**
 
     py.test
 
+**NOTE**: Requires py.test, install by `pip install pytest`
 
-Run integration tests
-=====================
-**WARNING**: These tests require an active Kafka cluster and will make use of a topic named 'test'.
+
+**Run integration tests:**
 
     examples/integration_test.py <kafka-broker>
 
+**WARNING**: These tests require an active Kafka cluster and will make use of a topic named 'test'.
+
+
 
 
 Generate documentation
@@ -51,7 +105,3 @@ or:
 Documentation will be generated in `docs/_build/`
 
 
-Examples
-========
-
-See [examples](examples)