Clean up README (uber-go#467)

Fix some small formatting and hyphenation errors in the readme, and correct the places where we're using "library" instead of "package."
amarjeetanandsingh · Jul 5, 2017 · 632ab30 · 632ab30
1 parent acea907
commit 632ab30
Show file tree

Hide file tree

Showing 3 changed files with 68 additions and 64 deletions.
diff --git a/.readme.tmpl b/.readme.tmpl
@@ -11,30 +11,31 @@ Note that zap only supports the two most recent minor versions of Go.
 ## Quick Start
 
 In contexts where performance is nice, but not critical, use the
-`SugaredLogger`. It's 4-10x faster than than other structured logging libraries
-and includes both structured and `printf`-style APIs.
+`SugaredLogger`. It's 4-10x faster than than other structured logging
+packages and includes both structured and `printf`-style APIs.
 
 ```go
 logger, _ := zap.NewProduction()
 defer logger.Sync() // flushes buffer, if any
 sugar := logger.Sugar()
-sugar.Infow("Failed to fetch URL.",
-  // Structured context as loosely-typed key-value pairs.
+sugar.Infow("failed to fetch URL",
+  // Structured context as loosely typed key-value pairs.
   "url", url,
   "attempt", 3,
   "backoff", time.Second,
 )
 sugar.Infof("Failed to fetch URL: %s", url)
 ```
 
-When performance and type safety are critical, use the `Logger`. It's even faster than
-the `SugaredLogger` and allocates far less, but it only supports structured logging.
+When performance and type safety are critical, use the `Logger`. It's even
+faster than the `SugaredLogger` and allocates far less, but it only supports
+structured logging.
 
 ```go
 logger, _ := zap.NewProduction()
 defer logger.Sync()
-logger.Info("Failed to fetch URL.",
-  // Structured context as strongly-typed Field values.
+logger.Info("failed to fetch URL",
+  // Structured context as strongly typed Field values.
   zap.String("url", url),
   zap.Int("attempt", 3),
   zap.Duration("backoff", time.Second),
@@ -44,18 +45,18 @@ logger.Info("Failed to fetch URL.",
 ## Performance
 
 For applications that log in the hot path, reflection-based serialization and
-string formatting are prohibitively expensive &mdash; they're CPU-intensive and
-make many small allocations. Put differently, using `encoding/json` and
+string formatting are prohibitively expensive &mdash; they're CPU-intensive
+and make many small allocations. Put differently, using `encoding/json` and
 `fmt.Fprintf` to log tons of `interface{}`s makes your application slow.
 
 Zap takes a different approach. It includes a reflection-free, zero-allocation
-JSON encoder, and the base `Logger` strives to avoid serialization overhead and
-allocations wherever possible. By building the high-level `SugaredLogger` on
-that foundation, zap lets users *choose* when they need to count every
-allocation and when they'd prefer a more familiar, loosely-typed API.
+JSON encoder, and the base `Logger` strives to avoid serialization overhead
+and allocations wherever possible. By building the high-level `SugaredLogger`
+on that foundation, zap lets users *choose* when they need to count every
+allocation and when they'd prefer a more familiar, loosely typed API.
 
 As measured by its own [benchmarking suite][], not only is zap more performant
-than comparable structured logging libraries &mdash; it's also faster than the
+than comparable structured logging packages &mdash; it's also faster than the
 standard library. Like all benchmarks, take these with a grain of salt.<sup
 id="anchor-versions">[1](#footnote-versions)</sup>
 
@@ -72,23 +73,24 @@ Log a static string, without any context or `printf`-style templating:
 {{.BenchmarkWithoutFields}}
 
 ## Development Status: Stable
+
 All APIs are finalized, and no breaking changes will be made in the 1.x series
-of releases. Users of semver-aware dependency management systems should pin zap
-to `^1`.
+of releases. Users of semver-aware dependency management systems should pin
+zap to `^1`.
 
 <hr>
 
 Released under the [MIT License](LICENSE.txt).
 
 <sup id="footnote-versions">1</sup> In particular, keep in mind that we may be
-benchmarking against slightly older versions of other libraries. Versions are
+benchmarking against slightly older versions of other packages. Versions are
 pinned in zap's [glide.lock][] file. [↩](#anchor-versions)
 
 [doc-img]: https://godoc.org/go.uber.org/zap?status.svg
 [doc]: https://godoc.org/go.uber.org/zap
 [ci-img]: https://travis-ci.org/uber-go/zap.svg?branch=master
 [ci]: https://travis-ci.org/uber-go/zap
-[cov-img]: https://coveralls.io/repos/github/uber-go/zap/badge.svg?branch=master
-[cov]: https://coveralls.io/github/uber-go/zap?branch=master
+[cov-img]: https://codecov.io/gh/uber-go/zap/branch/master/graph/badge.svg
+[cov]: https://codecov.io/gh/uber-go/zap
 [benchmarking suite]: https://github.com/uber-go/zap/tree/master/benchmarks
 [glide.lock]: https://github.com/uber-go/zap/blob/master/glide.lock
diff --git a/README.md b/README.md
@@ -11,30 +11,31 @@ Note that zap only supports the two most recent minor versions of Go.
 ## Quick Start
 
 In contexts where performance is nice, but not critical, use the
-`SugaredLogger`. It's 4-10x faster than than other structured logging libraries
-and includes both structured and `printf`-style APIs.
+`SugaredLogger`. It's 4-10x faster than than other structured logging
+packages and includes both structured and `printf`-style APIs.
 
 ```go
 logger, _ := zap.NewProduction()
 defer logger.Sync() // flushes buffer, if any
 sugar := logger.Sugar()
-sugar.Infow("Failed to fetch URL.",
-  // Structured context as loosely-typed key-value pairs.
+sugar.Infow("failed to fetch URL",
+  // Structured context as loosely typed key-value pairs.
   "url", url,
   "attempt", 3,
   "backoff", time.Second,
 )
 sugar.Infof("Failed to fetch URL: %s", url)
 ```
 
-When performance and type safety are critical, use the `Logger`. It's even faster than
-the `SugaredLogger` and allocates far less, but it only supports structured logging.
+When performance and type safety are critical, use the `Logger`. It's even
+faster than the `SugaredLogger` and allocates far less, but it only supports
+structured logging.
 
 ```go
 logger, _ := zap.NewProduction()
 defer logger.Sync()
-logger.Info("Failed to fetch URL.",
-  // Structured context as strongly-typed Field values.
+logger.Info("failed to fetch URL",
+  // Structured context as strongly typed Field values.
   zap.String("url", url),
   zap.Int("attempt", 3),
   zap.Duration("backoff", time.Second),
@@ -44,69 +45,70 @@ logger.Info("Failed to fetch URL.",
 ## Performance
 
 For applications that log in the hot path, reflection-based serialization and
-string formatting are prohibitively expensive &mdash; they're CPU-intensive and
-make many small allocations. Put differently, using `encoding/json` and
+string formatting are prohibitively expensive &mdash; they're CPU-intensive
+and make many small allocations. Put differently, using `encoding/json` and
 `fmt.Fprintf` to log tons of `interface{}`s makes your application slow.
 
 Zap takes a different approach. It includes a reflection-free, zero-allocation
-JSON encoder, and the base `Logger` strives to avoid serialization overhead and
-allocations wherever possible. By building the high-level `SugaredLogger` on
-that foundation, zap lets users *choose* when they need to count every
-allocation and when they'd prefer a more familiar, loosely-typed API.
+JSON encoder, and the base `Logger` strives to avoid serialization overhead
+and allocations wherever possible. By building the high-level `SugaredLogger`
+on that foundation, zap lets users *choose* when they need to count every
+allocation and when they'd prefer a more familiar, loosely typed API.
 
 As measured by its own [benchmarking suite][], not only is zap more performant
-than comparable structured logging libraries &mdash; it's also faster than the
+than comparable structured logging packages &mdash; it's also faster than the
 standard library. Like all benchmarks, take these with a grain of salt.<sup
 id="anchor-versions">[1](#footnote-versions)</sup>
 
 Log a message and 10 fields:
 
-| Library | Time | Bytes Allocated | Objects Allocated |
+| Package | Time | Bytes Allocated | Objects Allocated |
 | :--- | :---: | :---: | :---: |
-| :zap: zap | 1526 ns/op | 704 B/op | 2 allocs/op |
-| :zap: zap (sugared) | 2274 ns/op | 1610 B/op | 20 allocs/op |
-| go-kit | 5854 ns/op | 2895 B/op | 66 allocs/op |
-| logrus | 9117 ns/op | 6092 B/op | 78 allocs/op |
-| lion | 9408 ns/op | 5807 B/op | 63 allocs/op |
-| apex/log | 17007 ns/op | 3832 B/op | 65 allocs/op |
-| log15 | 21290 ns/op | 5632 B/op | 93 allocs/op |
+| :zap: zap | 1692 ns/op | 705 B/op | 2 allocs/op |
+| :zap: zap (sugared) | 2507 ns/op | 1610 B/op | 20 allocs/op |
+| go-kit | 6327 ns/op | 2895 B/op | 66 allocs/op |
+| lion | 8036 ns/op | 5807 B/op | 63 allocs/op |
+| logrus | 8970 ns/op | 6092 B/op | 78 allocs/op |
+| apex/log | 17101 ns/op | 3832 B/op | 65 allocs/op |
+| log15 | 21398 ns/op | 5632 B/op | 93 allocs/op |
 
 Log a message with a logger that already has 10 fields of context:
 
-| Library | Time | Bytes Allocated | Objects Allocated |
+| Package | Time | Bytes Allocated | Objects Allocated |
 | :--- | :---: | :---: | :---: |
-| :zap: zap | 446 ns/op | 0 B/op | 0 allocs/op |
-| :zap: zap (sugared) | 599 ns/op | 80 B/op | 2 allocs/op |
-| lion | 5231 ns/op | 4074 B/op | 38 allocs/op |
-| go-kit | 6424 ns/op | 3046 B/op | 52 allocs/op |
-| logrus | 7578 ns/op | 4564 B/op | 63 allocs/op |
-| apex/log | 15697 ns/op | 2898 B/op | 51 allocs/op |
-| log15 | 15879 ns/op | 2642 B/op | 44 allocs/op |
+| :zap: zap | 467 ns/op | 0 B/op | 0 allocs/op |
+| :zap: zap (sugared) | 597 ns/op | 80 B/op | 2 allocs/op |
+| lion | 5172 ns/op | 4074 B/op | 38 allocs/op |
+| go-kit | 6892 ns/op | 3078 B/op | 53 allocs/op |
+| logrus | 8102 ns/op | 4564 B/op | 63 allocs/op |
+| apex/log | 15332 ns/op | 2897 B/op | 51 allocs/op |
+| log15 | 16905 ns/op | 2642 B/op | 44 allocs/op |
 
 Log a static string, without any context or `printf`-style templating:
 
-| Library | Time | Bytes Allocated | Objects Allocated |
+| Package | Time | Bytes Allocated | Objects Allocated |
 | :--- | :---: | :---: | :---: |
-| :zap: zap | 418 ns/op | 0 B/op | 0 allocs/op |
-| standard library | 524 ns/op | 80 B/op | 2 allocs/op |
-| :zap: zap (sugared) | 628 ns/op | 80 B/op | 2 allocs/op |
-| go-kit | 1011 ns/op | 656 B/op | 13 allocs/op |
-| lion | 1382 ns/op | 1224 B/op | 10 allocs/op |
-| logrus | 2263 ns/op | 1505 B/op | 27 allocs/op |
-| apex/log | 3198 ns/op | 584 B/op | 11 allocs/op |
-| log15 | 5787 ns/op | 1592 B/op | 26 allocs/op |
+| :zap: zap | 465 ns/op | 0 B/op | 0 allocs/op |
+| standard library | 602 ns/op | 80 B/op | 2 allocs/op |
+| :zap: zap (sugared) | 647 ns/op | 80 B/op | 2 allocs/op |
+| go-kit | 994 ns/op | 656 B/op | 13 allocs/op |
+| lion | 1402 ns/op | 1224 B/op | 10 allocs/op |
+| logrus | 2299 ns/op | 1505 B/op | 27 allocs/op |
+| apex/log | 3148 ns/op | 584 B/op | 11 allocs/op |
+| log15 | 6329 ns/op | 1592 B/op | 26 allocs/op |
 
 ## Development Status: Stable
+
 All APIs are finalized, and no breaking changes will be made in the 1.x series
-of releases. Users of semver-aware dependency management systems should pin zap
-to `^1`.
+of releases. Users of semver-aware dependency management systems should pin
+zap to `^1`.
 
 <hr>
 
 Released under the [MIT License](LICENSE.txt).
 
 <sup id="footnote-versions">1</sup> In particular, keep in mind that we may be
-benchmarking against slightly older versions of other libraries. Versions are
+benchmarking against slightly older versions of other packages. Versions are
 pinned in zap's [glide.lock][] file. [↩](#anchor-versions)
 
 [doc-img]: https://godoc.org/go.uber.org/zap?status.svg

diff --git a/internal/readme/readme.go b/internal/readme/readme.go
@@ -111,7 +111,7 @@ func getBenchmarkRows(benchmarkName string) (string, error) {
 	}
 	sort.Sort(benchmarkRowsByTime(benchmarkRows))
 	rows := []string{
-		"| Library | Time | Bytes Allocated | Objects Allocated |",
+		"| Package | Time | Bytes Allocated | Objects Allocated |",
 		"| :--- | :---: | :---: | :---: |",
 	}
 	for _, benchmarkRow := range benchmarkRows {