diff --git a/README.md b/README.md
index 6ecd78c..c76ccfa 100644
--- a/README.md
+++ b/README.md
@@ -14,55 +14,98 @@ if (bowser.msie && bowser.version <= 6) {
 ## 1.0.0 breaking changes
 `browser = require('bowser').browser;` becomes `browser = require('bowser');`
 
-## Flags set for detected Browsers[Engines]
+## Bowser Flags
+Your mileage may vary, but these flags should be set.  See Contributing below.
 
-  * `chrome`[`webkit`]
-  * `firefox`[`gecko`]
+``` js
+alert('Hello ' + bowser.name + ' ' + bowser.version);
+```
+
+### All detected browsers
+These flags are set for all detected browsers:
+
+* `name` - A human readable name for this browser.  E.g. 'Chrome', ''
+* `version` - Version number for the browser.  E.g. '32.0'
+
+Bowser makes a best guess to match name and version for unknown UA strings, so they may not be set.
+
+### Rendering Engine Flags
+If detected, one of these flags may be set to true:
+
+  * `webkit` - Chrome, Android, iOs, BB, etc.
+  * `gecko` - Firefox, etc.
+  * `msie`  - IE <= 11
+  * `msedge` - IE > 11
+
+Safari, Chrome and some other minor browsers will report that they have `webkit` engines.
+Firefox and Seamonkey will report that they have `gecko` engines.
+
+``` js
+if (bowser.webkit) {
+  // do stuff with safari & chrome & opera & android & blackberry & webos & silk
+}
+```
+
+### Device flags
+If detected, one of these flags may be set to true:
+
+  * `mobile` - All detected mobile OSes are additionally flagged `mobile`, **unless it's a tablet**
+  * `tablet` - If a tablet device is detected, the flag `tablet` is set **instead of `mobile`**.
+
+### Browsers flags
+If detected, one of these flags may be set to true.  The rendering engine flag is shown in []'s:
+
+  * `chrome` - [`webkit`]
+  * `firefox` - [`gecko`]
   * `msie`
   * `msedge`
-  * Android native browser as `android`[`webkit`]
-  * iOS native browser as `ios`[`webkit`]
-  * `opera`[`webkit` if >12]
-  * `phantom`[`webkit`]
-  * `safari`[`webkit`]
-  * `seamonkey`[`gecko`]
-  * BlackBerry native browser as `blackberry`[`webkit`]
-  * WebOS native browser as `webos`[`webkit`]
-  * Amazon Kindle browser as `silk`[`webkit`]
-  * Bada browser as `bada`[`webkit`]
-  * Tizen browser as `tizen`[`webkit`]
-  * Sailfish browser as `sailfish`[`gecko`]
+  * `safari` - [`webkit`]
+  * `android` native browser - [`webkit`]
+  * `ios` native browser - [`webkit`]
+  * `opera` - [`webkit` if >12]
+  * `phantom` - [`webkit`]
+  * `blackberry` native browser - [`webkit`]
+  * `webos` native browser - [`webkit`]
+  * `silk` Amazon Kindle browser  - [`webkit`]
+  * `bada` - [`webkit`]
+  * `tizen` - [`webkit`]
+  * `seamonkey` - [`gecko`]
+  * `sailfish` - [`gecko`]
 
 For all detected browsers the browser version is set in the `version` field.
 
-## Flags set for detected Operating Systems
+### OS Flags
+If detected, one of these flags may be set to true:
 
   * `mac`
-  *  Windows other than Windows Phone as `windows`
-  *  Windows Phone as `windowsphone`
-  * `linux` for Linux other than `android`, `chromeos`, `webos`, `tizen`, and `sailfish`
+  * `windows` - other than Windows Phone
+  * `windowsphone`
+  * `linux` - other than `android`, `chromeos`, `webos`, `tizen`, and `sailfish`
   * `chromeos`
   * `android`
-  * `ios` (`iphone`/`ipad`/`ipod`)
+  * `ios` - also sets one of `iphone`/`ipad`/`ipod`
   * `blackberry`
   * `firefoxos`
-  * `webos` (`touchpad`)
+  * `webos` - may also set `touchpad`
   * `bada`
   * `tizen`
   * `sailfish`
 
-Android, iOS, Windows Phone, WebOS, Bada, and Tizen will all report the OS version number if it is contained in the UA string in the `osversion` field. iOS is always reported as `ios` and additionally as `iphone`/`ipad`/`ipod`, whichever one matches best. If WebOS device is an HP TouchPad the flag `touchpad` is additionally set.
+`osversion` may also be set:
 
-All detected mobile OSes are additionally flagged `mobile`, **if they are not powering a tablet device**. If a tablet device is detected, the flag `tablet` is set instead.
+  * `osversion` - for Android, iOS, Windows Phone, WebOS, Bada, and Tizen.  If included in UA string.
 
-### Notes
-Safari, Chrome and some other minor browsers will report that they have `webkit` engines, Firefox and Seamonkey will report that they have `gecko` engines.
+iOS is always reported as `ios` and additionally as `iphone`/`ipad`/`ipod`, whichever one matches best.
+If WebOS device is an HP TouchPad the flag `touchpad` is additionally set.
 
-``` js
-if (bowser.webkit) {
-  // do stuff with safari & chrome & opera & android & blackberry & webos & silk
-}
-```
+### Browser capability grading
+One of these flags will be set:
+
+  * `a` - This browser has full capabilities
+  * `c` - This browser has degraded capabilities.  Serve simpler version
+  * `x` - This browser has minimal capabilities and is probably not well detected.
+
+There is no `b`.
 
 ### Ender Support
 
@@ -80,20 +123,6 @@ if (require('bowser').chrome) {
 }
 ```
 
-### Graded Browser Support
-
-``` js
-if (bowser.a) {
-  // support full feature set
-}
-else if (bowser.c) {
-  // serve degraded version
-}
-else {
-  // unsupported (bowser.x)
-}
-```
-
 ### Contributing
 If you'd like to contribute a change to bowser, modify the files in `src/`, then run the following (you'll need node + npm installed):