Tweak README

README.md

@@ -1,38 +1,44 @@
 # faket [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage][codecov-img]][codecov]
 
 
-Are your test helpers correct -- test them with `faket`.
+Are your test helpers correct -- be confident with faket.
 
 ## Introduction
 
-Test helper functions play a crucial role in
-encapsulating common validation patterns
-and keeping your tests DRY (Don't Repeat Yourself).
+Test helper functions taking a `testing.TB` are
+helpful for encapsulating common validation patterns
+and DRY'ing up tests (Don't Repeat Yourself).
 
-These helpers often accept a `testing.TB` to report failures
-but it can be tricky to test failure scenarios.
-
-As these helpers grow in complexity and become widely used,
-verifying their behaviour becomes important--
+These helpers are not immune from bugs and
+as they grow in complexity and become widely used.
+Verifying their behaviour becomes important--
 your tests' correctness depends upon them!
 
-Failure handling by test helpers is particularly critical:
- * Do they indicate all errors, or fail on required checks?
+How do you test scenarios where the helper is expected to fail?
+Using a real `testing.T` would fail the test,
+when you want the opposite:
+the test should fail if the helper passes unexpectedly
+but pass if the helper fails with the expected failures!
+
+faket lets you validate correctness of your helpers
+using a fake `testing.TB`, which provides insight
+into the full behaviour of the test function:
+
+ * Are all the expected errors reported?
+ * Did the helper `Fatal` the test?
  * Is the output formatted correctly
-   and does it include all relevant information?
+   with all the relevant information?
 
-`faket` addresses these challenges by providing a fake `testing.TB`
-so you can validate correctness of your test helpers
-and ensure the reported messages are accurate and meaningful.
+### Example
 
-Let's take an example helper used to verify
-if a string contains expected substrings in order:
+Let's test a helper used to verify
+a string contains expected substrings in order:
 
 ```go
 func StrContainsInOrder(t testing.TB, got string, contains ...string)
 ```
 
-`faket` can be used to test that the helper behaves as expected:
+With faket, both successful and failure scenarios can be tested:
 ```go
 func TestStrContainsInOrder(t *testing.T) {
   t.Run("correct order", func(t *testing.T) {
@@ -54,19 +60,19 @@ func TestStrContainsInOrder(t *testing.T) {
  * Fully-featured implementation of `testing.TB`
    including `Skip`, `Fatal`, and `Cleanup`.
  * Thoroughly tested against the real `testing.TB`
-   implementations to ensure correct behaviour
-   * E.g., ensuring skips within cleanups work the same way.
- * Panic handling.
+   to ensure correct behaviour.
+ * Panic handling to allow validation of expected panics.
 
 ## Installation
 
 `go get -u github.com/prashantv/faket`
 
 faket is only supported and tested against the 2 most recent minor versions of Go.
 
-## Development Status: Development
+## Development Status: Alpha
 
-This library is still in development, and is not API stable.
+This library is ready for use **in tests**,
+but it's _not_ API stable.
 
 [doc-img]: https://pkg.go.dev/badge/github.com/prashantv/zap
 [doc]: https://pkg.go.dev/github.com/prashantv/faket