docs(npm): update npm command docs

These are the base docs for the npm cli itself that populates `man npm`,
Mostly grammar fixes, some additions and clarifications in places, new
links to some appropriate other docs

PR-URL: https://github.com/npm/cli/pull/2565
Credit: @wraithgar
Close: #2565
Reviewed-by: @nlf

1 files changed, 60 insertions, 45 deletions

diff --git a/docs/content/commands/npm.md b/docs/content/commands/npm.md
index dc6ba3d25..d01146d37 100644
--- a/docs/content/commands/npm.md
+++ b/docs/content/commands/npm.md
@@ -20,36 +20,42 @@ npm is the package manager for the Node JavaScript platform.  It puts
 modules in place so that node can find them, and manages dependency
 conflicts intelligently.
 
-It is extremely configurable to support a wide variety of use cases.
-Most commonly, it is used to publish, discover, install, and develop node
+It is extremely configurable to support a variety of use cases.  Most
+commonly, you use it to publish, discover, install, and develop node
 programs.
 
 Run `npm help` to get a list of available commands.
 
 ### Important
 
-npm is configured to use npm, Inc.'s public registry at
+npm comes preconfigured to use npm's public registry at
 https://registry.npmjs.org by default. Use of the npm public registry is
-subject to terms of use available at https://www.npmjs.com/policies/terms.
+subject to terms of use available at
+https://www.npmjs.com/policies/terms.
 
-You can configure npm to use any compatible registry you like, and even run
-your own registry. Use of someone else's registry may be governed by their
-terms of use.
+You can configure npm to use any compatible registry you like, and even
+run your own registry. Use of someone else's registry is governed by
+their terms of use.
 
 ### Introduction
 
 You probably got npm because you want to install stuff.
 
-Use `npm install blerg` to install the latest version of "blerg".  Check out
-[`npm install`](/commands/npm-install) for more info.  It can do a lot of stuff.
+The very first thing you will most likely want to run in any node
+program is `npm install` to install its dependencies.
 
-Use the `npm search` command to show everything that's available.
-Use `npm ls` to show everything you've installed.
+You can also run `npm install blerg` to install the latest version of
+"blerg".  Check out [`npm install`](/commands/npm-install) for more
+info.  It can do a lot of stuff.
+
+Use the `npm search` command to show everything that's available in the
+public registry.  Use `npm ls` to show everything you've installed.
 
 ### Dependencies
 
-If a package references to another package with a git URL, npm depends
-on a preinstalled git.
+If a package lists a dependency using a git URL, npm will install that
+dependency using the [`git`](https://github.com/git-guides/install-git)
+command and will generate an error if it is not installed.
 
 If one of the packages npm tries to install is a native node module and
 requires compiling of C++ Code, npm will use
@@ -64,20 +70,22 @@ the [node-gyp Wiki](https://github.com/nodejs/node-gyp/wiki).
 
 ### Directories
 
-See [`folders`](/configuring-npm/folders) to learn about where npm puts stuff.
+See [`folders`](/configuring-npm/folders) to learn about where npm puts
+stuff.
 
 In particular, npm has two modes of operation:
 
-* global mode:
-  npm installs packages into the install prefix at
-  `prefix/lib/node_modules` and bins are installed in `prefix/bin`.
 * local mode:
   npm installs packages into the current project directory, which
-  defaults to the current working directory.  Packages are installed to
-  `./node_modules`, and bins are installed to `./node_modules/.bin`.
+  defaults to the current working directory.  Packages install to
+  `./node_modules`, and bins to `./node_modules/.bin`.
+* global mode:
+  npm installs packages into the install prefix at
+  `$npm_config_prefix/lib/node_modules` and bins to
+  `$npm_config_prefix/bin`.
 
 Local mode is the default.  Use `-g` or `--global` on any command to
-operate in global mode instead.
+run in global mode instead.
 
 ### Developer Usage
 
@@ -85,20 +93,22 @@ If you're using npm to develop and publish your code, check out the
 following help topics:
 
 * json:
-  Make a package.json file.  See [`package.json`](/configuring-npm/package-json).
+  Make a package.json file.  See
+  [`package.json`](/configuring-npm/package-json).
 * link:
-  For linking your current working code into Node's path, so that you
-  don't have to reinstall every time you make a change.  Use
-  `npm link` to do this.
+  Links your current working code into Node's path, so that you don't
+  have to reinstall every time you make a change.  Use [`npm
+  link`](/commands/npm-link) to do this.
 * install:
-  It's a good idea to install things if you don't need the symbolic link.
-  Especially, installing other peoples code from the registry is done via
-  `npm install`
+  It's a good idea to install things if you don't need the symbolic
+  link.  Especially, installing other peoples code from the registry is
+  done via [`npm install`](/commands/npm-install)
 * adduser:
-  Create an account or log in.  Credentials are stored in the
-  user config file.
+  Create an account or log in.  When you do this, npm will store
+  credentials in the user config file config file.
 * publish:
-  Use the `npm publish` command to upload your code to the registry.
+  Use the [`npm publish`](/commands/npm-publish`) command to upload your
+  code to the registry.
 
 #### Configuration
 
@@ -108,20 +118,20 @@ npm is extremely configurable.  It reads its configuration options from
 * Command line switches:
   Set a config with `--key val`.  All keys take a value, even if they
   are booleans (the config parser doesn't know what the options are at
-  the time of parsing).  If no value is provided, then the option is set
-  to boolean `true`.
+  the time of parsing).  If you do not provide a value (`--key`) then
+  the option is set to boolean `true`.
 * Environment Variables:
   Set any config by prefixing the name in an environment variable with
   `npm_config_`.  For example, `export npm_config_key=val`.
 * User Configs:
-  The file at $HOME/.npmrc is an ini-formatted list of configs.  If
+  The file at `$HOME/.npmrc` is an ini-formatted list of configs.  If
   present, it is parsed.  If the `userconfig` option is set in the cli
-  or env, then that will be used instead.
+  or env, that file will be used instead.
 * Global Configs:
-  The file found at ../etc/npmrc (from the node executable, by default
-  this resolves to /usr/local/etc/npmrc) will be parsed if it is found.
-  If the `globalconfig` option is set in the cli, env, or user config,
-  then that file is parsed instead.
+  The file found at `./etc/npmrc` (relative to the global prefix will be
+  parsed if it is found.  See [`npm prefix`](/commands/npm-prefix) for
+  more info on the global prefix.  If the `globalconfig` option is set
+  in the cli, env, or user config, then that file is parsed instead.
 * Defaults:
   npm's default configuration options are defined in
   lib/utils/config-defs.js.  These must not be changed.
@@ -132,15 +142,17 @@ See [`config`](/using-npm/config) for much much more information.
 
 Patches welcome!
 
-If you would like to contribute, but don't know what to work on, read
-the [contributing guidelines](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) 
-and check the issues list.
+If you would like to help, but don't know what to work on, read the
+[contributing
+guidelines](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) and
+check the issues list.
 
 ### Bugs
 
-When you find issues, please report them: <https://github.com/npm/cli/issues>
+When you find issues, please report them:
+<https://github.com/npm/cli/issues>
 
-Be sure to follow the template and bug reporting guidelines.
+Please be sure to follow the template and bug reporting guidelines.
 
 ### Feature Requests
 
@@ -153,8 +165,11 @@ Or suggest formal RFC proposals:
 * <https://github.com/npm/rfcs>
 
 ### See Also
+
 * [npm help](/commands/npm-help)
 * [package.json](/configuring-npm/package-json)
-* [npm install](/commands/npm-install)
-* [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)
+* [npm config](/commands/npm-config)
+* [npm install](/commands/npm-install)
+* [npm prefix](/commands/npm-prefix)
+* [npm publish](/commands/npm-publish)