docs: readability edits to readme (#55)

README.md

@@ -4,7 +4,7 @@
 
 React Shisell builds on [shisell](https://github.com/Soluto/shisell-js) and lets you easily integrate analytics into [react](https://github.com/facebook/react) apps.
 
-Its most basic design principle is that at the root of the react tree is the writer which does the actual writing to your favorite analytics service, and any component in the react tree enhance the shisell analytics dispatcher and add another Scope/ExtraData/Identity/etc.
+Its most basic design principle is that at the root of the react tree is the writer which does the actual writing to your favorite analytics service, and any component in the react tree enhances the shisell analytics dispatcher and adds another Scope/ExtraData/Identity/etc.
 
 ## API
 
@@ -23,9 +23,9 @@ Its most basic design principle is that at the root of the react tree is the wri
 
 ### `withAnalytics`
 
-Adds a prop called `analytics` which contains a `dispatcher` of type `shisell.AnalyticsDispatcher` which lets any component freely dispatch analytics using the dispatcher currently in context.
+Adds a prop called `analytics` that contains a `dispatcher` of type `shisell.AnalyticsDispatcher`, which lets any component freely dispatch analytics using the dispatcher currently in context.
 
-Example usage:
+Usage example:
 
 ```js
 class LoginPage extends React.Component {
@@ -51,9 +51,9 @@ enrichAnalytics(
 ```
 
 With `enrichAnalytics` you can extend the existing analytics dispatcher and add whatever you want to it using `shisell`'s standard capabilities.
-Usually used for adding a sub-scope, or some data you want all subcomponents to include in their analytics.
+This is usually used for adding a sub-scope, or some data you want all subcomponents to include in their analytics.
 
-Example usage:
+Usage example:
 
 ```js
 class LoginPage extends React.Component {
@@ -87,10 +87,10 @@ withAnalyticOnView({
 ```
 
 `withAnalyticOnView` is used for the very common case of wanting to dispatch an analytic whenever a component mounts.
-For example, dispatching an analytic whenever someone enters a specific page, or views a modal, etc.
+For example, dispatching an analytic whenever someone enters a specific page, views a modal, etc.
 It's also possible to supply a `shouldDispatchAnalytics` to only dispatch the analytic after a certain prop has a value (for example, data loaded from an async fetch).
 
-Example usage:
+Usage example:
 
 ```js
 const LoginPage = (props) => ...;
@@ -116,16 +116,16 @@ withAnalyticOnEvent({
 ```
 
 `withAnalyticOnEvent` is used when we need an event handler that dispatches analytics.
-For example, a button that triggers some action, and dispatches an analytic.
+For example, a button that triggers some action and dispatches an analytic.
 The `eventName` is also the name of the prop the event handler will be injected into (if it already exists, it will be wrapped).
 There are two ways to add data to the sent analytic:
 
-1. Statically - with `extendAnalytics` which will let you add extras/identities from the event itself.
+1. Statically - with `extendAnalytics`, which will let you add extras/identities from the event itself.
 2. Dynamically with props - the resulting component will accept an `extendAnalytics` prop which behaves the same as the static counterpart.
 
 In addition, the component will receive a `shouldDispatchAnalytics` prop which can be a `boolean` or a `(...params) => boolean` predicate.
 
-Example usage:
+Usage example:
 
 ```js
 const LoginPage = (props) => <button onClick={onButtonClick}>Login here</button>;
@@ -158,14 +158,14 @@ withOnPropChangedAnalytic({
 ```
 
 `withOnPropChangedAnalytic` triggers an analytic dispatch whenever a specified property changes.
-It's meant for cases where there's a property which signals a change in state, and that state change should be recorded as an analytic.
+It's meant for cases where there's a property that signals a change in state, and that state change should be recorded as an analytic.
 For example, 'LoggingIn' becoming 'LoginFailure'.
 In these cases you usually only want to send the analytic once when the property changes, and not on every subsequent re-render.
 
 `includeFirstValue` is set to false by default. If set to true, the valueFilter function will be tested on (undefined, firstPropValue) and will dispatch if true.  
-_Notice: providing `includeFirstValue: true` and not providing a valueFilter function will always result in dispatching on mount, regardless what's the specified prop value is._
+_Notice: providing `includeFirstValue: true` and not providing a valueFilter function will always result in dispatching on mount, regardless of what the specified prop value is._
 
-Example usage:
+Usage example:
 
 ```js
 const LoginPage = (props) => ...;
@@ -181,10 +181,10 @@ ReactDOM.render(<EnhancedLoginPage onButtonClick={(e) => console.log(e)} />);
 
 ### `useAnalytics`
 
-react hook that returns an object which contains a `dispatcher` of type `shisell.AnalyticsDispatcher` which lets any component freely dispatch analytics using the dispatcher currently in context.
-same as `withAnalytics` but with hooks.
+React hook that returns an object which contains a `dispatcher` of type `shisell.AnalyticsDispatcher`, which lets any component freely dispatch analytics using the dispatcher currently in context.
+Same as `withAnalytics` but with hooks.
 
-Example usage:
+Usage example:
 
 ```js
 const MyComponent = (props) => {
@@ -197,9 +197,9 @@ const MyComponent = (props) => {
 
 ### `useAnalyticCallback`
 
-React hook to create analytic dispatcher functions. Simpler than using the analytics context from `useAnalytics()`
+React hook to create analytic dispatcher functions. Simpler than using the analytics context from `useAnalytics()`.
 
-Example usage:
+Usage example:
 
 ```ts
 // create function to dispatch event
@@ -217,9 +217,9 @@ const value = await fetchWithAnalytic('arg');
 
 ### `AnalyticsProvider`
 
-React analytics context provider to override or transform the analytics dispatcher
+React analytics context provider to override or transform the analytics dispatcher.
 
-Example usage:
+Usage example:
 
 ```tsx
 const ExampleComponent = ({user, children}: ExampleComponentProps) => (
@@ -239,12 +239,12 @@ analytics: {
 }
 ```
 
-The `analytics` object is the connection between `shisell` and `react-shisell`, essentially.
+The `analytics` object is essentially the connection between `shisell` and `react-shisell`.
 It holds the event writer and the current root dispatcher.
 It's used to dynamically set the event writer, and to transform the dispatcher for all analytics sent.
 For example, after successfuly logging in, you'd want all analytics sent to include a `UserId` identity.
 
-Example usage:
+Usage example:
 
 ```js
 login().then((user) => analytics.transformDispatcher((dispatcher) => dispatcher.extend(withExtra('UserId', user.id))));