doc: recommend against use of NODE_PATH

PR-URL: #1708
Reviewed-By: Roman Reiss <me@silverwind.io>

doc/api/modules.markdown

@@ -429,6 +429,18 @@ of absolute paths, then io.js will search those paths for modules if they
 are not found elsewhere.  (Note: On Windows, `NODE_PATH` is delimited by
 semicolons instead of colons.)
 
+`NODE_PATH` was originally created to support loading modules from
+varying paths before the current
+[module resolution](https://iojs.org/api/modules.html#modules_all_together)
+algorithm was frozen.
+
+`NODE_PATH` is still supported, but is less necessary now that the io.js
+ecosystem has settled on a convention for locating dependent modules.
+Sometimes deployments that rely on `NODE_PATH` show surprising behavior
+when people are unaware that `NODE_PATH` must be set.  Sometimes a
+module's dependencies change, causing a different version (or even a
+different module) to be loaded as the `NODE_PATH` is searched.
+
 Additionally, io.js will search in the following locations:
 
 * 1: `$HOME/.node_modules`
@@ -438,9 +450,9 @@ Additionally, io.js will search in the following locations:
 Where `$HOME` is the user's home directory, and `$PREFIX` is io.js's
 configured `node_prefix`.
 
-These are mostly for historic reasons.  You are highly encouraged to
-place your dependencies locally in `node_modules` folders.  They will be
-loaded faster, and more reliably.
+These are mostly for historic reasons.  **You are highly encouraged
+to place your dependencies locally in `node_modules` folders.**  They
+will be loaded faster, and more reliably.
 
 ## Accessing the main module