docs: clean up the native module tutorial (#17951)

docs/tutorial/using-native-node-modules.md

@@ -1,25 +1,57 @@
 # Using Native Node Modules
 
-The native Node modules are supported by Electron, but since Electron is very
-likely to use a different V8 version from the Node binary installed in your
-system, you have to manually specify the location of Electron's headers when
-building native modules.
+Native Node modules are supported by Electron, but since Electron is very
+likely to use a different V8 version from the Node binary installed on your
+system, the modules you use will need to be recompiled for Electron. Otherwise,
+you will get the following class of error when you try to run your app:
+
+```sh
+Error: The module '/path/to/native/module.node'
+was compiled against a different Node.js version using
+NODE_MODULE_VERSION $XYZ. This version of Node.js requires
+NODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing
+the module (for instance, using `npm rebuild` or `npm install`).
+```
 
 ## How to install native modules
 
-Three ways to install native modules:
+There are several different ways to install native modules:
+
+### Installing modules and rebuilding for Electron
+
+You can install modules like other Node projects, and then rebuild the modules
+for Electron with the [`electron-rebuild`][electron-rebuild] package. This
+module can automatically determine the version of Electron and handle the
+manual steps of downloading headers and rebuilding native modules for your app.
+
+For example, to install `electron-rebuild` and then rebuild modules with it
+via the command line:
+
+```sh
+npm install --save-dev electron-rebuild
+
+# Every time you run "npm install", run this:
+./node_modules/.bin/electron-rebuild
+
+# On Windows if you have trouble, try:
+.\node_modules\.bin\electron-rebuild.cmd
+```
+
+For more information on usage and integration with other tools, consult the
+project's README.
 
 ### Using `npm`
 
 By setting a few environment variables, you can use `npm` to install modules
 directly.
 
-An example of installing all dependencies for Electron:
+For example, to install all dependencies for Electron:
 
 ```sh
 # Electron's version.
 export npm_config_target=1.2.3
-# The architecture of Electron, can be ia32 or x64.
+# The architecture of Electron, see https://electronjs.org/docs/tutorial/support#supported-platforms
+# for supported architectures.
 export npm_config_arch=x64
 export npm_config_target_arch=x64
 # Download headers for Electron.
@@ -32,25 +64,6 @@ export npm_config_build_from_source=true
 HOME=~/.electron-gyp npm install
 ```
 
-### Installing modules and rebuilding for Electron
-
-You can also choose to install modules like other Node projects, and then
-rebuild the modules for Electron with the [`electron-rebuild`][electron-rebuild]
-package. This module can get the version of Electron and handle the manual steps
-of downloading headers and building native modules for your app.
-
-An example of installing `electron-rebuild` and then rebuild modules with it:
-
-```sh
-npm install --save-dev electron-rebuild
-
-# Every time you run "npm install", run this:
-./node_modules/.bin/electron-rebuild
-
-# On Windows if you have trouble, try:
-.\node_modules\.bin\electron-rebuild.cmd
-```
-
 ### Manually building for Electron
 
 If you are a developer developing a native module and want to test it against
@@ -62,44 +75,44 @@ cd /path-to-module/
 HOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://atom.io/download/electron
 ```
 
-The `HOME=~/.electron-gyp` changes where to find development headers. The
-`--target=1.2.3` is version of Electron. The `--dist-url=...` specifies
-where to download the headers. The `--arch=x64` says the module is built for
-64bit system.
+* `HOME=~/.electron-gyp` changes where to find development headers.
+* `--target=1.2.3` is the version of Electron.
+* `--dist-url=...` specifies where to download the headers.
+* `--arch=x64` says the module is built for a 64-bit system.
 
 ### Manually building for a custom build of Electron
 
-To compile native Node addons against a custom build of Electron that doesn't
+To compile native Node modules against a custom build of Electron that doesn't
 match a public release, instruct `npm` to use the version of Node you have bundled
 with your custom build.
 
 ```sh
-npm rebuild --nodedir=$HOME/.../path/to/electron/vendor/node
+npm rebuild --nodedir=/path/to/electron/vendor/node
 ```
 
 ## Troubleshooting
 
 If you installed a native module and found it was not working, you need to check
-following things:
+the following things:
 
-* The architecture of the module has to match Electron's architecture (ia32 or x64).
-* `win_delay_load_hook` is not set to `false` in the module's `binding.gyp`.
-* After you upgrade Electron, you usually need to rebuild the modules.
 * When in doubt, run `electron-rebuild` first.
+* Make sure the native module is compatible with the target platform and
+  architecture for your Electron app.
+* Make sure `win_delay_load_hook` is not set to `false` in the module's `binding.gyp`.
+* After you upgrade Electron, you usually need to rebuild the modules.
 
 ### A note about `win_delay_load_hook`
 
-On Windows, by default, node-gyp links native modules against `node.dll`.
+On Windows, by default, `node-gyp` links native modules against `node.dll`.
 However, in Electron 4.x and higher, the symbols needed by native modules are
-exported by `electron.exe`, and there is no `node.dll` in Electron 4.x. In
-order to load native modules on Windows, node-gyp installs a [delay-load
+exported by `electron.exe`, and there is no `node.dll`. In order to load native
+modules on Windows, `node-gyp` installs a [delay-load
 hook](https://msdn.microsoft.com/en-us/library/z9h1h6ty.aspx) that triggers
 when the native module is loaded, and redirects the `node.dll` reference to use
 the loading executable instead of looking for `node.dll` in the library search
 path (which would turn up nothing). As such, on Electron 4.x and higher,
 `'win_delay_load_hook': 'true'` is required to load native modules.
 
-
 If you get an error like `Module did not self-register`, or `The specified
 procedure could not be found`, it may mean that the module you're trying to use
 did not correctly include the delay-load hook.  If the module is built with
@@ -125,12 +138,13 @@ In particular, it's important that:
 - `win_delay_load_hook.obj` is linked directly into the final DLL. If the hook
   is set up in a dependent DLL, it won't fire at the right time.
 
-See [node-gyp](https://github.com/nodejs/node-gyp/blob/e2401e1395bef1d3c8acec268b42dc5fb71c4a38/src/win_delay_load_hook.cc) for an example delay-load hook if you're implementing your own.
+See [`node-gyp`](https://github.com/nodejs/node-gyp/blob/e2401e1395bef1d3c8acec268b42dc5fb71c4a38/src/win_delay_load_hook.cc)
+for an example delay-load hook if you're implementing your own.
 
 ## Modules that rely on `prebuild`
 
-[`prebuild`](https://github.com/mafintosh/prebuild) provides a way to
-publish native Node modules with prebuilt binaries for multiple versions of Node
+[`prebuild`](https://github.com/prebuild/prebuild) provides a way to publish
+native Node modules with prebuilt binaries for multiple versions of Node
 and Electron.
 
 If modules provide binaries for the usage in Electron, make sure to omit
@@ -143,13 +157,13 @@ The [`node-pre-gyp` tool][node-pre-gyp] provides a way to deploy native Node
 modules with prebuilt binaries, and many popular modules are using it.
 
 Usually those modules work fine under Electron, but sometimes when Electron uses
-a newer version of V8 than Node, and there are ABI changes, bad things may
-happen. So in general it is recommended to always build native modules from
-source code.
+a newer version of V8 than Node and/or there are ABI changes, bad things may
+happen. So in general, it is recommended to always build native modules from
+source code. `electron-rebuild` handles this for you automatically.
 
 If you are following the `npm` way of installing modules, then this is done
 by default, if not, you have to pass `--build-from-source` to `npm`, or set the
 `npm_config_build_from_source` environment variable.
 
-[electron-rebuild]: https://github.com/paulcbetts/electron-rebuild
+[electron-rebuild]: https://github.com/electron/electron-rebuild
 [node-pre-gyp]: https://github.com/mapbox/node-pre-gyp