diff --git a/README.md b/README.md
index 0682998..457f619 100644
--- a/README.md
+++ b/README.md
@@ -1,73 +1,103 @@
-# goodparts [](https://github.com/dwyl/good-parts/issues) [](https://travis-ci.org/dwyl/goodparts)
+# `goodparts`
+
+An ESLint Plugin that _only_ allows **JavaScript the _Good_ Parts**
+(_and "**Better Parts**"_) in your code so you can _ship_ more reliable code.
+
+[](https://travis-ci.org/dwyl/goodparts)
[](https://david-dm.org/dwyl/goodparts)
[](https://david-dm.org/dwyl/goodparts?type=dev)
+[](https://github.com/dwyl/good-parts/issues)
-An ESLint Style that _only_ allows JavaScript the ***Good Parts*** (*and "Better Parts"*) in your code you can sleep at night.
## *Why?*
-Because this is the _best_ way we know how to write consistent,
-predictable and error free JavaScript code.
+Using JavaScript "**The _Good_ Parts**" (_abreviated to **`"goodparts"`**_)
+is the _best_ way we know
+how to write consistent,
+_predictable_ and 100% cross-browser-compatible JavaScript code.
-Our ***guiding principal*** is:
+The ***guiding principal*** of `goodparts` is:
> "***perfection*** *is* ***attained*** *not when there is nothing more to add,
> but when there is* ***nothing more to remove***" ~
[Antoine de Saint-Exupéry](http://en.wikiquote.org/wiki/Antoine_de_Saint_Exup%C3%A9ry#Quotes)
-we subscribe to the "_code is for **humans** to read_" idea:
+We _agree_ that "_code is for **humans** to read_":
-> "_**Programs must be written for people to read**, and only incidentally for machines to execute._" ~ Harold Abelson
+> "_**Programs must be written for people to read**,
+and only incidentally for machines to execute._" ~ Harold Abelson
-> "_Any fool can write code that a computer can understand.
+> "_Any fool can write code that a computer can understand.
**Good programmers write code** that **humans** can
**understand**._" ~ Martin Fowler
-Also, we agree with:
-
-> "_**constraints** can actually **boost creativity**_". [Martin Villeneuve](https://www.ted.com/talks/martin_villeneuve_how_i_made_an_impossible_film)
-
The 3 biggest advantages of using `goodparts` in your code:
1. [***Readability***](https://en.wikipedia.org/wiki/Readability) - using _fewer_ ECMAScript (JS) language features means
people reading your code can get to the heart of what it *does*
rather than waste time trying to understand
how its been written.
-2. [***Shoshin***](https://en.wikipedia.org/wiki/Shoshin) - using _fewer_ JS features
-also means a _complete_ beginner has _less_ to learn before
-they _understand_ your code. This is _essential_ in Open Source
-if you want to make something that _anyone_ can use/modify/extend.
-3. [***Portability***](https://en.wikipedia.org/wiki/Software_portability) -
+2. [***Portability***](https://en.wikipedia.org/wiki/Software_portability) -
"Old" Browsers/Devices are a _fact_, even if it's "*only a small percentage*"
of people, we _chose_ to
[*empathize*](http://www.merriam-webster.com/dictionary/empathize)
with them by writing code that ***Works Everywhere***TM.
-
+3. ***Beginner-friendlyness*** or [***Shoshin***](https://en.wikipedia.org/wiki/Shoshin) - using _fewer_ JS features
+also means a _complete_ beginner has _less_ to learn before
+they _understand_ your code. This is _essential_ in Open Source
+if you want to make something that _anyone_ can use/modify/extend.
## *What?*
-A one-line install that will ensure your project's code works everywhere.
-(_or your money back!_)
+`goodparts` is a "[linter](https://en.wikipedia.org/wiki/Lint_%28software%29)"
+that _ensures_ your project's JavaScript code
+only contains the _subset_ of JavaScript known as "**The _Good_ Parts**".
+This _**guarantees**_ that
+your code ***works everywhere***. (_or your money back!_)
+
+
+### What _are_ "**The _Good_ Parts**"
+> If you are _unfamiliar_ with JavaScript "**The _Good_ Parts**"
+or need a _refresher_,
+please see @iteles' notes: [github.com/iteles/Javascript-the-**_Good_**-**Parts**-_**notes**_](https://github.com/iteles/Javascript-the-Good-Parts-notes)
+There are _several_ videos where Douglas Crockford covers
+the Why? What? and How?
+of JavaScript "**The _Good_ Parts**"
+see: https://github.com/dwyl/goodparts/#videos
+
+
## *How?*
-Simply install our configuration
+
+First _install_ the [**NPM Package**](https://www.npmjs.com/package/goodparts)
+in your Node.js/JS project:
```
-$ npm i --save-dev goodparts
+$ npm install goodparts --save-dev
```
-Then you can add the following script to your `package.json`:
+Then add the following script to your `package.json`:
```
{
"lint": "node_modules/.bin/goodparts path/to/files/for/linting"
}
```
+> Example: ...
+
+Now when you run the command:
+
+```sh
+npm run lint
+```
+You should _either_ see
+
+or you should see
@@ -87,7 +117,12 @@ file, so you need to specify your environment e.g:
## Why (_extended version_)
-### Why Should Anyone _Listen_ to Douglas Crockford?
+We _strongly_ agree with the following sentiment/quote:
+
+> "_**constraints** can actually **boost creativity**_". [Martin Villeneuve](https://www.ted.com/talks/martin_villeneuve_how_i_made_an_impossible_film)
+
+
+### _Why_ Should Anyone _Listen_ to `Douglas Crockford`?
There are *many* places you can go to learn JavaScript,
*unsurprisingly* they *all* claim to teach you the "right way",
@@ -100,7 +135,8 @@ learning is any good is by listening to their their peers
or failing that, "*gut feeling*", neither of which are
a *reliable* measure of _quality_.
-Crockford is the Master Yoda of JavaScript, he has truly mastered the craft.
+Crockford is the "[Yoda](https://youtu.be/7YkbgvRMpW0?t=55s)"
+of JavaScript, he has truly [_mastered_](https://en.wikipedia.org/wiki/Mastery_learning) the craft.
He is a member of "[**TC39**](http://tc39wiki.calculist.org/about/people/)"
(the ECMAScript Technical Committee) responsible for
setting the language _standard_ to be implemented by web browser makers;
@@ -212,31 +248,18 @@ https://www.nngroup.com/articles/legibility-readability-comprehension/
-
-### _Should_ We Use ECMAScript 2015 (*AKA "ES6"*)?
-
-When you see someone _trying_ to use ***all*** the
-***latest features*** of **ECMAScript 2015**,
-its clear they are just trying to *look* smart to their piers
-and have not stopped to think/ask:
-+ "_will this code **work everywhere**_?"
-+ "_did the **users** ask me to use this (new) language feature_?
-(_or is there an existing way of doing this reliably...?_)"
-+ "_if I'm just going to transpile this through babel or add a pollyfill
-(for cross-browser compatibility) which means users have to load more bytes of code
-in their browser, what is true the advantage_...?"
-
-
-### Why does this matter / should I care?
+### Why does this matter / should I _care_?
If you are lucky enough to be building an *internal* web app
(*e.g: an intranet or "internal tools") and you "*know*" that
-everyone in the company is using Chrome that's *awesome*,
-thank your lucky stars and enjoy using all the latest & greatest features!
+_**everyone**_ in the company/organisation is using **"_Latest Chrome_"**
+that's *awesome*,
+thank your _lucky stars_ and enjoy using all the latest & greatest features of
+**ES6**!
If, like us, you live in the "*real world*" and build applications/websites
-that need to be *accessible* by and work *consistently* on any device/browser,
-then using only the *goodparts* is a good idea.
+that need to be *accessible* by and work *consistently* on _any_ device/browser,
+then using only the ***`goodparts`*** is a good idea.
> We are ***not suggesting*** that you (*your team/company*) *should*
> (*explicitly*) ***support IE8*** running on Windows XP! (*heavens no!*)
@@ -244,6 +267,28 @@ then using only the *goodparts* is a good idea.
*everywhere* so you don't have to *think* about it.
+### ES2015?
+
+The 6th edition JavaScript, _officially_ known as "**ES6**" or **ECMAScript _2015_**, was finalized in June 2015.
+This update adds significant new syntax for writing complex applications, including classes and modules
+
+https://en.wikipedia.org/wiki/ECMAScript#6th_Edition_-_ECMAScript_2015
+
+#### _Should_ We Use ECMAScript 2015 (*AKA "ES6"*)?
+
+When you see someone _trying_ to use ***all*** the
+***latest features*** of **ECMAScript 2015**,
+
+think/ask:
++ "_will this code **work everywhere**_?"
++ "_did the **users** ask me to use this (new) language feature_?
+(_or is there an `existing` way of doing this reliably...?_)"
++ "_if I'm just going to "**transpile**" this through babel or add a pollyfill
+(for cross-browser compatibility) which means users have to load more bytes of code
+in their browser (so pages take longer to load), what is true the advantage_...?"
+
+
### But caniuse.com says ...
Caniuse.com is a *fantastic* website. The UI is brilliant and for "*informal*"
@@ -275,7 +320,7 @@ please don't take their usage tables as "*gospel*" because they are flawed.
## Browser Stats *Facts*
-Most of us live in a *technology bubble*, we take it for granted
+Most of us live in a *technology bubble*, we take it for _granted_
that we always have Wifi or 4G and assume that because many of our
friends/colleagues are using MacBook Pros or iPhone 6s that
*everyone* is in the same situation.
@@ -303,7 +348,10 @@ they cannot; which means we are *relying* on non-technical people to
and had a person ask "*what is a browser*?" you will know that
*might* take a while...
+If you want to dive a bit deeper into the methodology used by StatCounter see:
+http://www.zdnet.com/article/net-market-share-vs-statcounter-whose-online-measurements-can-you-trust/
+