doc: adjustments to the README.md for new users

PR-URL: #1919
Reviewed-By: Rod Vagg <[email protected]>

Author: Dan Pike

README.md

@@ -3,8 +3,7 @@
 `node-gyp` is a cross-platform command-line tool written in Node.js for
 compiling native addon modules for Node.js. It contains a fork of the
 [gyp](https://gyp.gsrc.io) project that was previously used by the Chromium
-team and takes away the pain of dealing with the various differences in build
-platforms.
+team, extended to support the development of Node.js native addons.
 
 Note that `node-gyp` is _not_ used to build Node.js itself.
 
@@ -14,23 +13,18 @@ etc.), regardless of what version of Node.js is actually installed on your syste
 
 ## Features
 
- * Easy to use, consistent interface
- * Same commands to build your module on every platform
- * Supports multiple target versions of Node.js
+ * The same build commands work on any of the supported platforms
+ * Supports the targetting of different versions of Node.js
 
 ## Installation
 
-You can install with `npm`:
+You can install `node-gyp` using `npm`:
 
 ``` bash
 $ npm install -g node-gyp
 ```
 
-You will also need to install:
-
-NOTE: node-gyp is compatible with Python v2.7, v3.5, v3.6, or v3.7. If the
-Python to use is not explicitly configured (see "Configuring Python Dependency"
-below) it will attempt to find a compatible Python executable.
+Depending on your operating system, you will need to install:
 
 ### On Unix
 
@@ -67,27 +61,30 @@ Install tools and configuration manually:
 
 ### Configuring Python Dependency
 
-If you have multiple Python versions installed, you can identify which Python
-version `node-gyp` uses by setting the `--python` variable:
+`node-gyp` requires that you have installed a compatible version of Python, one of: v2.7, v3.5, v3.6,
+or v3.7. If you have multiple Python versions installed, you can identify which Python
+version `node-gyp` should use in one of the following ways:
+
+1. by setting the `--python` command-line option, e.g.:
 
 ``` bash
 $ node-gyp <command> --python /path/to/executable/python
 ```
 
-If `node-gyp` is called by way of `npm`, *and* you have multiple versions of
+2. If `node-gyp` is called by way of `npm`, *and* you have multiple versions of
 Python installed, then you can set `npm`'s 'python' config key to the appropriate
 value:
 
 ``` bash
 $ npm config set python /path/to/executable/python
 ```
 
-If the `PYTHON` environment variable is set to the path of a Python executable,
-it will be used if it is a compatible Python.
+3. If the `PYTHON` environment variable is set to the path of a Python executable,
+then that version will be used, if it is a compatible version.
 
-If the `NODE_GYP_FORCE_PYTHON` environment variable is set to the path of a
+4. If the `NODE_GYP_FORCE_PYTHON` environment variable is set to the path of a
 Python executable, it will be used instead of any of the other configured or
-builtin Python search paths. If its not a compatible Python, no further
+builtin Python search paths. If it's not a compatible version, no further
 searching will be done.
 
 ## How to Use
@@ -147,15 +144,16 @@ A barebones `gyp` file appropriate for building a Node.js addon could look like:
 }
 ```
 
-Some additional resources for addons and writing `gyp` files:
+## Further reading
+
+Some additional resources for Node.js native addons and writing `gyp` configuration files:
 
  * ["Going Native" a nodeschool.io tutorial](http://nodeschool.io/#goingnative)
  * ["Hello World" node addon example](https://github.com/nodejs/node/tree/master/test/addons/hello-world)
  * [gyp user documentation](https://gyp.gsrc.io/docs/UserDocumentation.md)
  * [gyp input format reference](https://gyp.gsrc.io/docs/InputFormatReference.md)
  * [*"binding.gyp" files out in the wild* wiki page](https://github.com/nodejs/node-gyp/wiki/%22binding.gyp%22-files-out-in-the-wild)
 
-
 ## Commands
 
 `node-gyp` responds to the following commands: