expanded documentation for using Oj to replace JSON (#714)

* expanded documentation for using Oj to replace JSON

* doc improvements wip

README.md

@@ -43,6 +43,15 @@ or in Bundler:
 gem 'oj'
 ```
 
+## Rails and json quickstart
+
+See the Quickstart sections of the [Rails](pages/Rails.md) and [json](pages/JsonGem.md) docs.
+
+## multi_json
+
+Code which uses [multi_json](https://github.com/intridea/multi_json)
+will automatically prefer Oj if it is installed.
+
 ## Support
 
 [Get supported Oj with a Tidelift Subscription.](https://tidelift.com/subscription/pkg/rubygems-oj?utm_source=rubygems-oj&utm_medium=referral&utm_campaign=readme) Security updates are [supported](https://tidelift.com/security).

pages/JsonGem.md

@@ -1,3 +1,18 @@
+# JSON Quickstart
+
+To have Oj universally "take over" many methods on the JSON constant (`load`, `parse`, etc.) with
+their faster Oj counterparts, in a mode that is compatible with the json gem:
+
+```ruby
+Oj.mimic_JSON()
+```
+
+If the project does not already use the json gem, `JSON` will become available.
+If the project does require the json gem, `Oj.mimic_JSON()` should be invoked after the
+json gem has been required.
+
+For more details and options, read on...
+
 # Oj JSON Gem Compatibility
 
 The `:compat` mode mimics the json gem. The json gem is built around the use

pages/Modes.md

@@ -39,7 +39,8 @@ if a non-native type is encountered instead of raising an Exception.
 The `:compat` mode mimics the json gem. The json gem is built around the use
 of the `to_json(*)` method defined for a class. Oj attempts to provide the
 same functionality by being a drop in replacement with a few
-exceptions. [{file:JsonGem.md}](JsonGem.md) includes more details on
+exceptions. To universally replace many `JSON` methods with their faster Oj counterparts,
+simply run `Oj.mimic_json`. [{file:JsonGem.md}](JsonGem.md) includes more details on
 compatibility and use.
 
 ## :rails Mode

pages/Rails.md

@@ -1,3 +1,15 @@
+# Rails Quickstart
+
+To universally replace Rails' use of the json gem with Oj, and also
+have Oj "take over" many methods on the JSON constant (`load`, `parse`, etc.) with
+their faster Oj counterparts, add this to an initializer:
+
+```ruby
+Oj.optimize_rails()
+```
+
+For more details and options, read on...
+
 # Oj Rails Compatibility
 
 The `:rails` mode mimics the ActiveSupport version 5 encoder. Rails and