Improvements to README and documentation [ci skip]

* Include more thorough before/after example
* Reduce duplication of examples / explanations
* Ensure documentation is up to date
* Add/remove `require` statements where needed