Improve README layout (@jeffwidman, #606)

Author: jeffwidman

README.md

@@ -152,13 +152,11 @@ go build -tags musl ./...
 A dependency to the latest stable version of confluent-kafka-go should be automatically added to
 your `go.mod` file.
 
-
-
 Install the client
 ------------------
 
 If Go modules can't be used we recommend that you version pin the
-confluent-kafka-go import to v1 using gopkg.in:
+confluent-kafka-go import to `v1` using gopkg.in:
 
 Manual install:
 ```bash
@@ -184,15 +182,13 @@ The following platforms are supported by the prebuilt librdkafka binaries:
 When building your application for Alpine Linux (musl libc) you must pass
 `-tags musl` to `go get`, `go build`, etc.
 
-`CGO_ENABLED` must NOT be set to 0 since the Go client is based on the
+`CGO_ENABLED` must NOT be set to `0` since the Go client is based on the
 C library librdkafka.
 
 If GSSAPI/Kerberos authentication support is required you will need
 to install librdkafka separately, see the **Installing librdkafka** chapter
 below, and then build your Go application with `-tags dynamic`.
 
-
-
 Installing librdkafka
 ---------------------
 
@@ -216,26 +212,24 @@ Build from source:
     make
     sudo make install
 
-
 After installing librdkafka you will need to build your Go application
 with `-tags dynamic`.
 
-**Note:** If you use the master branch of the Go client, then you need to use
-          the master branch of librdkafka.
+**Note:** If you use the `master` branch of the Go client, then you need to use
+          the `master` branch of librdkafka.
 
 **confluent-kafka-go requires librdkafka v1.6.0 or later.**
 
 
-
 API Strands
 ===========
 
-There are two main API strands: function and channel based.
+There are two main API strands: function and channel-based.
 
-Function Based Consumer
+Function-Based Consumer
 -----------------------
 
-Messages, errors and events are polled through the consumer.Poll() function.
+Messages, errors and events are polled through the `consumer.Poll()` function.
 
 Pros:
 
@@ -244,19 +238,18 @@ Pros:
 Cons:
 
  * Makes it harder to read from multiple channels, but a go-routine easily
-   solves that (see Cons in channel based consumer above about outdated events).
+   solves that (see Cons in channel-based consumer below about outdated events).
  * Slower than the channel consumer.
 
 See [examples/consumer_example](examples/consumer_example)
 
-
-Channel Based Consumer (deprecated)
+Channel-Based Consumer (deprecated)
 -----------------------------------
 
-*Deprecated*: The channel based consumer is deprecated due to the channel issues
-              mentioned below. Use the function based consumer.
+*Deprecated*: The channel-based consumer is deprecated due to the channel issues
+              mentioned below. Use the function-based consumer.
 
-Messages, errors and events are posted on the consumer.Events channel
+Messages, errors and events are posted on the `consumer.Events()` channel
 for the application to read.
 
 Pros:
@@ -273,16 +266,11 @@ Cons:
 
 See [examples/consumer_channel_example](examples/consumer_channel_example)
 
-
-
-
-
-
-Channel Based Producer
+Channel-Based Producer
 ----------------------
 
-Application writes messages to the producer.ProducerChannel.
-Delivery reports are emitted on the producer.Events or specified private channel.
+Application writes messages to the `producer.ProducerChannel()`.
+Delivery reports are emitted on the `producer.Events()` or specified private channel.
 
 Pros:
 
@@ -296,20 +284,19 @@ Cons:
 
 See [examples/producer_channel_example](examples/producer_channel_example)
 
-
-Function Based Producer
+Function-Based Producer
 -----------------------
 
-Application calls producer.Produce() to produce messages.
-Delivery reports are emitted on the producer.Events or specified private channel.
+Application calls `producer.Produce()` to produce messages.
+Delivery reports are emitted on the `producer.Events()` or specified private channel.
 
 Pros:
 
  * Go:ish
 
 Cons:
 
- * Produce() is a non-blocking call, if the internal librdkafka queue is full
+ * `Produce()` is a non-blocking call, if the internal librdkafka queue is full
    the call will fail.
  * Somewhat slower than the channel producer.
 
@@ -331,4 +318,4 @@ See [kafka/README](kafka/README.md)
 
 Contributions to the code, examples, documentation, et.al, are very much appreciated.
 
-Make your changes, run gofmt, tests, etc, push your branch, create a PR, and [sign the CLA](http://clabot.confluent.io/cla).
+Make your changes, run `gofmt`, tests, etc, push your branch, create a PR, and [sign the CLA](http://clabot.confluent.io/cla).