improve readme

README.MD

@@ -1,12 +1,10 @@
 # Agnostic Axe
 
-Test your web application with the [axe-core](https://github.com/dequelabs/axe-core) accessibility testing library. Results will show in the browser console.
+Agnostic axe logs accessibility issues to the browser console, as you develop your app. It's audits are powered by [axe-core](https://github.com/dequelabs/axe-core).
 
-## Installation
+## Basic Usage
 
-You can install the module from NPM via (`npm install --save-dev agnostic-axe`) or directly import it from the URL, as shown below:
-
-## Usage
+Install the module from NPM (`npm install --save-dev agnostic-axe`) or directly import it from the URL:
 
 ```js
 import('https://unpkg.com/agnostic-axe@2').then(
@@ -17,39 +15,40 @@ import('https://unpkg.com/agnostic-axe@2').then(
 )
 ```
 
-> Be sure to only run the module in your development environment. Else your application will use more resources than necessary when in production.
+> Be sure to only run the module in your development environment. Else your application will use more resources than necessary when in production. ([Webpack-Example](WEBPACK_EXAMPLE.MD))
+
+## Advanced Configuration
+
+The `AxeObserver` constructor takes two parameters:
+
+- `violationsCallback` (required). A function that is invoked with an array of violations, as reported by [axe-core](https://github.com/dequelabs/axe-core). To log violations to the console, simply pass the `logViolations` function exported by this module.
+- `options` (optional). An object with that supports the following configuration keys:
+  - `axeCoreConfiguration` (optional). [A configuration object for axe-core](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axeconfigure). Overwrites the default configuration used by agnostic axe.
+  - `axeCoreInstanceCallback` (optional). A callback that is invoked with the [axe-core](https://github.com/dequelabs/axe-core) instance.
 
-In the example above, once the `observe` method has been invoked, `MyAxeObserver` audits the passed node and reports any accessibility defects to the browser console. It continously observes the passed node for changes. If a change has been detected, it will audit the parts of the nodes that have changed, and report any new accessibility defects.
+The `AxeObserver.observe` method takes one parameter:
 
-To observe multiple nodes, one can call the `observe` method multiple times.
+- `targetNode` (required). AxeObserver performs an audit of this node, and continously monitors it for changes. If a change has been detected, AxeObserver audits the parts that have changed, and reports any new accessibility defects.
 
-> Note that due to a [limitation of axe-core](https://github.com/dequelabs/axe-core/pull/1914), there should never be more than one instance of AxeObserver running in the same enviroment.
+To observe multiple nodes, simply call the `AxeObserver.observe` method multiple times. There should never be more than one instance of AxeObserver running in the same enviroment.
 
 ```js
-MyAxeObserver.observe(root1)
-MyAxeObserver.observe(root2)
-MyAxeObserver.observe(root3)
+MyAxeObserver.observe(document.getElementById('react-main'))
+MyAxeObserver.observe(document.getElementById('vue-header'))
+MyAxeObserver.observe(document.getElementById('page-footer'))
 ```
 
-To stop observing changes, one can call the `disconnect` method.
+To stop observing changes, call the `disconnect` method.
 
 ```js
 MyAxeObserver.disconnect()
 ```
 
-### Configuration
-
-The `AxeObserver` constructor takes two parameters:
-
-- `violationsCallback` (required). A function that is invoked with an array of violations, as reported by [axe-core](https://github.com/dequelabs/axe-core). To log violations to the console, simply pass the `logViolations` function exported by this module.
-- `options` (optional). An object with that supports the following configuration keys:
-  - `axeCoreConfiguration` (optional). A configuration object for axe-core. Read about the object here in the [axe-core docs](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axeconfigure) and see the `agnostic-axe` source code for the default options used.
-  - `axeCoreInstanceCallback` (optional). A function that is invoked with the instance of [axe-core](https://github.com/dequelabs/axe-core) used by module. It can be used for complex interactions with the [axe-core API](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md) such as registering plugins.
-
-The `AxeObserver.observe` method takes one parameter:
+## Advantages
 
-- `targetNode` (required). The node that should be observed & analyzed.
+Unlike framework specific implementations of [axe-core](https://github.com/dequelabs/axe-core), such as [react-axe](https://github.com/dequelabs/react-axe), agnostic axe uses a [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) to listens for changes directly in the DOM. This has two advantages:
 
-## Credits
+1. It always works with the newest version of your framework (and even if you switch technologies). For example, at the time of writing, [react-axe](https://github.com/dequelabs/react-axe) does not support function components or fragments, while agnostic axe does.
+2. It only reruns audits if the actual DOM changes. This means it uses resources than [react-axe](https://github.com/dequelabs/react-axe), which audits whenever components rerender, even if their output does not change.
 
-Agnostic axe itself is merely a wrapper around [axe-core](https://github.com/dequelabs/axe-core) that employs a `MutationObserver` to detect DOM changes automatically. Most of its logic for formatting violations return by [axe-core](https://github.com/dequelabs/axe-core) is taken from [react-axe](https://github.com/dequelabs/react-axe).
+Aside from this, agnostic axe is optimized for performance. Its audits are small chunks of work, that are run in the browser's idle periods.

WEDPACK_EXAMPLE.MD

@@ -0,0 +1,14 @@
+# Webpack Example
+
+```js
+if (process.env.NODE_ENV !== 'production') {
+  // Import agnostic axe here.
+  // Webpack will comment out this code in production.
+  import('https://unpkg.com/agnostic-axe@2').then(
+    ({ AxeObserver, logViolations }) => {
+      const MyAxeObserver = new AxeObserver(logViolations)
+      MyAxeObserver.observe(document)
+    }
+  )
+}
+```