docs($readme): add Complete Example using history package

README.md

@@ -2,7 +2,11 @@
 
 Pluggable browser scroll management.
 
-**If you use [React Router](https://github.com/reactjs/react-router), use [react-router-scroll](https://github.com/taion/react-router-scroll), which wraps up the scroll management logic here into a React Router middleware.**
+**If you use [React Router](https://github.com/reactjs/react-router), use [react-router-scroll](https://github.com/taion/react-router-scroll), which wraps up the scroll management logic here into a React Router middleware.** 
+
+**If you're using the latest React Router (v4), feel free to try out its fork: https://github.com/ytase/react-router-scroll. There is one potential issue when using redirects, which may or may not be a problem for you. See ongoing discussion in [#52](https://github.com/taion/react-router-scroll/issues/52).**
+
+**For a** ***redux-first*** **routing solution that makes use of `scroll-behavior`, checkout: [redux-first-router](https://github.com/faceyspacey/redux-first-router).**
 
 [![Codecov][codecov-badge]][codecov]
 [![Discord][discord-badge]][discord]
@@ -93,6 +97,25 @@ scrollBehavior.registerScrollElement(
 
 To unregister an element, call the `unregisterElement` method with the key used to register that element.
 
+
+### Examples
+This package is typically not used directly, but rather used to power scroll restoration solutions for popular routing libraries. If you're looking to build your own (perhaps for another routing solution), we recommend first checking out the following implementations:
+
+- https://github.com/taion/react-router-scroll
+- https://github.com/4Catalyzer/found-scroll
+- https://github.com/ytase/react-router-scroll *(React Router v4 fork of `react-router-scroll`; notice how `history.listen` from the popular `history` package is used for `addTransitionHook`)*
+- https://github.com/faceyspacey/redux-first-router-restore-scroll *(shows how to use the  `history` package to configure `scroll-behavior`, but leaves calling `updateScroll` to be handled manually)*
+
+The key element of most the above packages is how `updateScroll` is called in a top level `<Context />` component on `componentDidUpdate` when the given router's location has changed:
+
+- https://github.com/taion/react-router-scroll/blob/v0.4.2/src/ScrollBehaviorContext.js#L40-L49
+- https://github.com/4Catalyzer/found-scroll/blob/v0.1.2/src/ScrollManager.js#L35-L44
+
+In addition, if your routing library handles data fetching, you likely want to call `updateScroll` again after the data has been fetched and the page re-rendered. This allows `scroll-behavior` to scroll to a portion of the page that might not have loaded before. The same also applies if you're using code-splitting and loading additional chunks. In that case you'll also want to call `updateScroll` after components from the new chunk have rendered.
+
+If your routing library does not handle data fetching, you may want to expose an `updateScroll` function of your own so developers can call it at the appropriate time in userland. Perhaps your users don't want a `<Context />` component constantly re-rendering (even if just in the virtual DOM), and would rather call `updateScroll` in `componentDidUpdate` callbacks that already exist. This has the benefit of reducing the amount of rendering work to be done *(cycles add up!)*, which can be key to providing the best experience in large animation-heavy applications.
+
+
 [build-badge]: https://img.shields.io/travis/taion/scroll-behavior/master.svg
 [build]: https://travis-ci.org/taion/scroll-behavior