Update README to better reflect primary usage

[ci skip]

Author: mcmire

README.md

@@ -3,149 +3,147 @@
 [version-badge]: http://img.shields.io/gem/v/super_diff.svg
 [rubygems]: http://rubygems.org/gems/super_diff
 [travis-badge]: http://img.shields.io/travis/mcmire/super_diff/master.svg
-[travis]: http://travis-ci.org/mcmire/super_diff
 [downloads-badge]: http://img.shields.io/gem/dtv/super_diff.svg
 [hound-badge]: https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg
 [hound]: https://houndci.com
 
-## Concept
+SuperDiff is a tool that displays the differences between two data structures of
+any type in Ruby.
+
+## Introduction
 
-SuperDiff is a utility that helps you diff two complex data structures in Ruby
-and gives you helpful output to show you exactly how the two data structures
-differ.
+The primary motivation behind this gem is to replace RSpec's built-in diffing
+capabilities. Sometimes, whenever you use a matcher such as `eq`, `match`,
+`include`, or `have_attributes`, you will get a diff of the two data structures
+you are trying to match against. This is really helpful for strings, but not so
+helpful for other, more "real world" kinds of values, such as arrays, hashes,
+and full-scale objects. The reason this doesn't work is because [RSpec will
+naively run your `expected` and `actual` values through Ruby's PrettyPrinter
+library][rspec-differ-fail] and then perform a diff of these strings.
 
-Let's say you have two hashes and you want to compare them. Perhaps your first
-hash looks like this:
+For instance, let's say you wanted to compare these two hashes:
 
 ``` ruby
-expected = {
+actual = {
   customer: {
-    name: "Marty McFly",
+    person: SuperDiff::Test::Person.new(name: "Marty McFly, Jr.", age: 17),
     shipping_address: {
-      line_1: "123 Main St.",
+      line_1: "456 Ponderosa Ct.",
       city: "Hill Valley",
       state: "CA",
-      zip: "90382",
-    },
+      zip: "90382"
+    }
   },
   items: [
     {
       name: "Fender Stratocaster",
       cost: 100_000,
-      options: ["red", "blue", "green"],
+      options: ["red", "blue", "green"]
     },
-    { name: "Chevy 4x4" },
-  ],
+    { name: "Mattel Hoverboard" }
+  ]
 }
-```
-
-and your second hash looks like this:
 
-``` ruby
-actual = {
+expected = {
   customer: {
-    name: "Marty McFly, Jr.",
+    person: SuperDiff::Test::Person.new(name: "Marty McFly", age: 17),
     shipping_address: {
-      line_1: "456 Ponderosa Ct.",
+      line_1: "123 Main St.",
       city: "Hill Valley",
       state: "CA",
-      zip: "90382",
-    },
+      zip: "90382"
+    }
   },
   items: [
     {
       name: "Fender Stratocaster",
       cost: 100_000,
-      options: ["red", "blue", "green"],
+      options: ["red", "blue", "green"]
     },
-    { name: "Mattel Hoverboard" },
-  ],
+    { name: "Chevy 4x4" }
+  ]
 }
 ```
 
-If you want to know what the difference between them is, you could say:
+If, somewhere in a test, you were to say:
 
 ``` ruby
-SuperDiff::EqualityMatcher.call(expected, actual)
+expect(actual).to eq(expected)
 ```
 
-This will give you the following string:
+You would get output that looks like:
 
-```
-Differing hashes.
-
-Expected: { customer: { name: "Marty McFly", shipping_address: { line_1: "123 Main St.", city: "Hill Valley", state: "CA", zip: "90382" } }, items: [{ name: "Fender Stratocaster", cost: 100000, options: ["red", "blue", "green"] }, { name: "Chevy 4x4" }] }
-Got: { customer: { name: "Marty McFly, Jr.", shipping_address: { line_1: "456 Ponderosa Ct.", city: "Hill Valley", state: "CA", zip: "90382" } }, items: [{ name: "Fender Stratocaster", cost: 100000, options: ["red", "blue", "green"] }, { name: "Mattel Hoverboard" }] }
-
-Diff:
-
-  {
-    customer: {
--     name: "Marty McFly",
-+     name: "Marty McFly, Jr.",
-      shipping_address: {
--       line_1: "123 Main St.",
-+       line_1: "456 Ponderosa Ct.",
-        city: "Hill Valley",
-        state: "CA",
-        zip: "90382"
-      }
-    },
-    items: [
-      {
-        name: "Fender Stratocaster",
-        cost: 100000,
-        options: ["red", "blue", "green"]
-      },
-      {
--       name: "Chevy 4x4"
-+       name: "Mattel Hoverboard"
-      }
-    ]
-  }
-```
+![Before super_diff](doc/before_super_diff.png)
+
+Not great.
 
-When printed to a terminal, this will display in color, so the "expected" value
-in the summary and deleted lines in the diff will appear in red, while the
-"actual" value in the summary and inserted lines in the diff will appear in
-green.
+This library provides a sophisticated set of comparators that know how to
+intelligent compute the differences between two data structures and display them
+in a way that makes sense. Using the example above, you'd get this instead:
 
-By the way, SuperDiff doesn't just work with hashes, but arrays as well as other
-objects, too!
+![After super_diff](doc/after_super_diff.png)
 
-## Usage
+[rspec-differ-fail]: https://github.com/rspec/rspec-support/blob/c69a231d7369dd165ad7ce4742e1a2e21e3462b5/lib/rspec/support/differ.rb#L178
 
-There are two ways to use this gem. One way is to use the API methods that this
-gem provides, such as the method presented above.
+## Installation
 
-However, this gem was really designed for use specifically with RSpec. In recent
-years, RSpec has added a feature where if you're comparing two objects in a test
-and your test fails, you will see a diff between those objects (provided the
-objects are large enough). However, this diff is not always the most helpful.
-It's very common when writing tests for API endpoints to work with giant JSON
-hashes, and RSpec's diffs are not sufficient in highlighting changes between
-such structures. Therefore, this gem provides an integration layer where you can
-replace RSpec's differ with SuperDiff.
+Want to try out this gem for yourself? As with most development-related gems,
+there are a couple ways depending on your type of project:
 
-To get started, add the gem to your Gemfile under the `test` group:
+### Rails apps
+
+If you're developing a Rails app, add the following to your Gemfile:
 
 ``` ruby
 gem "super_diff"
 ```
 
-Then, open up `spec_helper` and add this line somewhere:
+After running `bundle install`, add the following to your `rails_helper`:
 
 ``` ruby
 require "super_diff/rspec"
 ```
 
-Now try writing a test using `eq` to compare two large data structures, and you
-should see a diff similar to the one given above.
+You're done!
+
+### Libraries
+
+If you're developing a library, add the following to your gemspec:
+
+``` ruby
+spec.add_development_dependency "super_diff"
+```
+
+Now add the following to your `spec_helper`:
+
+``` ruby
+require "super_diff/rspec"
+```
+
+You're done!
+
+## Configuration
+
+As capable as this library is, it doesn't know how to deal with every kind of
+object out there. You might find it necessary to instruct the gem on how to diff
+your object. To do this, you can use a configuration block. Simply add this to
+your test helper file (either `rails_helper` or `spec_helper`):
+
+``` ruby
+SuperDiff::RSpec.configure do |config|
+  config.extra_differ_classes << YourDiffer
+  config.extra_operational_sequencer_classes << YourOperationalSequencer
+  config.extra_diff_formatter_classes << YourDiffFormatter
+end
+```
+
+*(More info here in the future on adding a custom differ, operational sequencer,
+and diff formatter. Also explanations on what these are.)*
 
 ## Contributing
 
-If you encounter a bug or have an idea for how this could be better, I'm all
-ears! Feel free to create an issue.
+If you encounter a bug or have an idea for how this could be better, feel free
+to create an issue.
 
 If you'd like to submit a PR instead, here's how to get started. First, fork
 this repo and then run:
@@ -169,6 +167,13 @@ bundle exec rspec spec/unit/...
 
 Finally, submit your PR and I'll take a look at it when I get a chance.
 
+## Compatibility
+
+`super_diff` is [tested][travis] to work with RSpec 3.x, Ruby >= 2.4.x, and
+JRuby >= 9.2.x.
+
+[travis]: http://travis-ci.org/mcmire/super_diff
+
 ## Copyright/License
 
-© 2018 Elliot Winkler, released under the [MIT license](LICENSE).
+© 2018-2019 Elliot Winkler, released under the [MIT license](LICENSE).