Some new readability updates (#54)

README.md

@@ -10,7 +10,7 @@ Uber's [zap](https://godoc.org/go.uber.org/zap) library pioneered this approach.
 
 To keep the code base and the API simple, zerolog focuses on efficient structured logging only. Pretty logging on the console is made possible using the provided (but inefficient) `zerolog.ConsoleWriter`.
 
-![](pretty.png)
+![Pretty Logging Image](pretty.png)
 
 ## Who uses zerolog
 
@@ -34,11 +34,13 @@ Find out [who uses zerolog](https://github.com/rs/zerolog/wiki/Who-uses-zerolog)
 ```go
 go get -u github.com/rs/zerolog/log
 ```
+
 ## Getting Started
 
 ### Simple Logging Example
 
 For simple logging, import the global logger package **github.com/rs/zerolog/log**
+
 ```go
 package main
 
@@ -58,8 +60,35 @@ func main() {
 
 // Output: {"time":1516134303,"level":"debug","message":"hello world"}
 ```
+
 > Note: The default log level for `log.Print` is *debug*
 
+### Contextual Logging
+
+**zerolog** allows data to be added to log messages in the form of key:value pairs. The data added to the message adds "context" about the log event that can be critical for debugging as well as myriad other purposes. An example of this is below:
+
+```go
+package main
+
+import (
+    "github.com/rs/zerolog"
+    "github.com/rs/zerolog/log"
+)
+
+func main() {
+    zerolog.TimeFieldFormat = ""
+
+    log.Debug().
+        Str("Scale", "833 cents").
+        Float64("Interval", 833.09).
+        Msg("Fibonacci is everywhere")
+}
+
+// Output: {"time":1524104936,"level":"debug","Scale":"833 cents","Interval":833.09,"message":"Fibonacci is everywhere"}
+```
+
+> You'll note in the above example that when adding contextual fields, the fields are strongly typed. You can find the full list of supported fields [here](#standard-types)
+
 ### Leveled Logging
 
 #### Simple Leveled Logging Example
@@ -81,13 +110,16 @@ func main() {
 // Output: {"time":1516134303,"level":"info","message":"hello world"}
 ```
 
+> It is very important to note that when using the **zerolog** chaining API, as shown above (`log.Info().Msg("hello world"`), the chain must have either the `Msg` or `Msgf` method call. If you forget to add either of these, the log will not occur and there is no compile time error to alert you of this.
+
 **zerolog** allows for logging at the following levels (from highest to lowest):
-- panic (`zerolog.PanicLevel`, 5)
+
-- fatal (`zerolog.FatalLevel`, 4)
+* panic (`zerolog.PanicLevel`, 5)
-- error (`zerolog.ErrorLevel`, 3)
+* fatal (`zerolog.FatalLevel`, 4)
-- warn (`zerolog.WarnLevel`, 2)
+* error (`zerolog.ErrorLevel`, 3)
-- info (`zerolog.InfoLevel`, 1)
+* warn (`zerolog.WarnLevel`, 2)
-- debug (`zerolog.DebugLevel`, 0)
+* info (`zerolog.InfoLevel`, 1)
+* debug (`zerolog.DebugLevel`, 0)
 
 You can set the Global logging level to any of these options using the `SetGlobalLevel` function in the zerolog package, passing in one of the given constants above, e.g. `zerolog.InfoLevel` would be the "info" level.  Whichever level is chosen, all logs with a level greater than or equal to that level will be written. To turn off logging entirely, pass the `zerolog.Disabled` constant.
 
@@ -127,13 +159,16 @@ func main() {
     }
 }
 ```
+
 Info Output (no flag)
+
 ```bash
 $ ./logLevelExample
 {"time":1516387492,"level":"info","message":"This message appears when log level set to Debug or Info"}
 ```
 
 Debug Output (debug flag set)
+
 ```bash
 $ ./logLevelExample -debug
 {"time":1516387573,"level":"debug","message":"This message appears only when log level set to Debug"}
@@ -141,6 +176,29 @@ $ ./logLevelExample -debug
 {"time":1516387573,"level":"debug","foo":"bar","message":"some debug message"}
 ```
 
+#### Logging without Level or Message
+
+You may choose to log without a specific level by using the `Log` method. You may also write without a message by setting an empty string in the `msg string` parameter of the `Msg` method. Both are demonstrated in the example below.
+
+```go
+package main
+
+import (
+    "github.com/rs/zerolog"
+    "github.com/rs/zerolog/log"
+)
+
+func main() {
+    zerolog.TimeFieldFormat = ""
+
+    log.Log().
+        Str("foo", "bar").
+        Msg("")
+}
+
+// Output: {"time":1494567715,"foo":"bar"}
+```
+
 #### Logging Fatal Messages
 
 ```go
@@ -168,21 +226,9 @@ func main() {
 // Output: {"time":1516133263,"level":"fatal","error":"A repo man spends his life getting into tense situations","service":"myservice","message":"Cannot start myservice"}
 //         exit status 1
 ```
+
 > NOTE: Using `Msgf` generates one allocation even when the logger is disabled.
 
-### Contextual Logging
-
-#### Fields can be added to log messages
-
-```go
-log.Info().
-    Str("foo", "bar").
-    Int("n", 123).
-    Msg("hello world")
-
-// Output: {"level":"info","time":1494567715,"foo":"bar","n":123,"message":"hello world"}
-```
-
 ### Create logger instance to manage different outputs
 
 ```go
@@ -241,14 +287,6 @@ log.Info().Msg("hello world")
 // Output: {"l":"info","t":1494567715,"m":"hello world"}
 ```
 
-### Log with no level nor message
-
-```go
-log.Log().Str("foo","bar").Msg("")
-
-// Output: {"time":1494567715,"foo":"bar"}
-```
-
 ### Add contextual fields to the global logger
 
 ```go
@@ -430,20 +468,20 @@ Some settings can be changed and will by applied to all loggers:
 
 ## Binary Encoding
 
-In addition to the default JSON encoding, `zerolog` can produce binary logs using the [cbor](http://cbor.io) encoding. The choice of encoding can be decided at compile time using the build tag `binary_log` as follow:
+In addition to the default JSON encoding, `zerolog` can produce binary logs using [CBOR](http://cbor.io) encoding. The choice of encoding can be decided at compile time using the build tag `binary_log` as follows:
 
-```
+```bash
 go build -tags binary_log .
 ```
 
 To Decode binary encoded log files you can use any CBOR decoder. One has been tested to work
-with zerolog library is CSD(https://github.com/toravir/csd/).
+with zerolog library is [CSD](https://github.com/toravir/csd/).
 
 ## Benchmarks
 
 All operations are allocation free (those numbers *include* JSON encoding):
 
-```
+```text
 BenchmarkLogEmpty-8        100000000    19.1 ns/op     0 B/op       0 allocs/op
 BenchmarkDisabled-8        500000000    4.07 ns/op     0 B/op       0 allocs/op
 BenchmarkInfo-8            30000000     42.5 ns/op     0 B/op       0 allocs/op
@@ -453,8 +491,8 @@ BenchmarkLogFields-8       10000000	   184 ns/op	   0 B/op       0 allocs/op
 
 There are a few Go logging benchmarks and comparisons that include zerolog.
 
-- [imkira/go-loggers-bench](https://github.com/imkira/go-loggers-bench)
+* [imkira/go-loggers-bench](https://github.com/imkira/go-loggers-bench)
-- [uber-common/zap](https://github.com/uber-go/zap#performance)
+* [uber-common/zap](https://github.com/uber-go/zap#performance)
 
 Using Uber's zap comparison benchmark: