Revamp README

Author: edenhill

README.md

@@ -24,7 +24,7 @@ with Apache Kafka at its core. It's high priority for us that client features ke
 pace with core Apache Kafka and components of the [Confluent Platform](https://www.confluent.io/product/compare/).
 
 The Python bindings provides a high-level Producer and Consumer with support
-for the balanced consumer groups of Apache Kafka 0.9.
+for the balanced consumer groups of Apache Kafka >= 0.9.
 
 See the [API documentation](http://docs.confluent.io/current/clients/confluent-kafka-python/index.html) for more info.
 
@@ -42,6 +42,7 @@ 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.poll(0)
 p.flush()
 ```
 
@@ -124,9 +125,8 @@ version it may use. This is done through two configuration settings:
 
 When using a Kafka 0.10 broker or later you don't need to do anything
 (`api.version.request=true` is the default).
-If you use Kafka broker 0.9 or 0.8 you must set
-`api.version.request=false` and set
-`broker.version.fallback` to your broker version,
+If you use Kafka broker 0.9 or 0.8 you must set `api.version.request=false`
+and set `broker.version.fallback` to your broker version,
 e.g `broker.version.fallback=0.9.0.1`.
 
 More info here:
@@ -136,33 +136,39 @@ https://github.com/edenhill/librdkafka/wiki/Broker-version-compatibility
 Prerequisites
 =============
 
- * Python >= 2.6 or Python 3.x
- * [librdkafka](https://github.com/edenhill/librdkafka) >= 0.9.1 (embedded in Linux wheels)
+ * Python >= 2.7 or Python 3.x
+ * ([librdkafka](https://github.com/edenhill/librdkafka) >= 0.9.2)
 
-librdkafka is embedded in the manylinux wheels, for other platforms or
-when a specific version of librdkafka is desired, following these guidelines:
+The latest version of librdkafka is embedded in the OSX and manylinux wheels,
+for other platforms or when a specific version of librdkafka is desired, follow these guidelines:
 
-  * For **Debian/Ubuntu**** based systems, add this APT repo and then do `sudo apt-get install librdkafka-dev python-dev`:
+ * For **Debian/Ubuntu** based systems, add the Confluent APT repository and then do `sudo apt-get install librdkafka-dev python-dev`:
 http://docs.confluent.io/current/installation.html#installation-apt
 
- * For **RedHat** and **RPM**-based distros, add this YUM repo and then do `sudo yum install librdkafka-devel python-devel`:
+ * For **RedHat** and **RPM**-based distros, add the Confluent YUM repository and then do `sudo yum install librdkafka-devel python-devel`:
 http://docs.confluent.io/current/installation.html#rpm-packages-via-yum
 
  * On **OSX**, use **homebrew** and do `sudo brew install librdkafka`
 
+**NOTE:** The pre-built manylinux wheels do NOT contain SASL Kerberos support. If you need SASL Kerberos support you must install librdkafka and its dependencies using the above repositories and then build confluent-kafka from source using the instructions below.
+
 
 Install
 =======
 
-**Install from PyPi:**
+**Install self-contained binary wheels for OSX and Linux from PyPi:**
 
     $ pip install confluent-kafka
 
-    # for AvroProducer or AvroConsumer
+**Install AvroProducer and AvroConsumer:**
+
     $ pip install confluent-kafka[avro]
 
+**Install from source from PyPi** *(requires librdkafka + dependencies to be installed separately)*:
+
+    $ pip install --no-binary :all: confluent-kafka
 
-**Install from source / tarball:**
+**Install from source directory:**
 
     $ pip install .