a couple doc improvements / fixes

doc/api/documentation.md

@@ -11,20 +11,16 @@ Where appropriate, property types, method arguments, and the arguments
 provided to event handlers are detailed in a list underneath the topic
 heading.
 
-Every `.html` document has a corresponding `.json` document presenting
-the same information in a structured manner. This feature is
-experimental, and added for the benefit of IDEs and other utilities that
-wish to do programmatic things with the documentation.
-
-Every `.html` and `.json` file is generated based on the corresponding
-`.md` file in the `doc/api/` folder in Node.js's source tree. The
-documentation is generated using the `tools/doc/generate.js` program.
-The HTML template is located at `doc/template.html`.
-
+## Contributing
 
 If errors are found in this documentation, please [submit an issue][]
 or see [the contributing guide][] for directions on how to submit a patch.
 
+Every file is generated based on the corresponding `.md` file in the
+`doc/api/` folder in Node.js's source tree. The documentation is generated
+using the `tools/doc/generate.js` program. An HTML template is located at
+`doc/template.html`.
+
 ## Stability Index
 
 <!--type=misc-->
@@ -53,40 +49,43 @@ is not recommended in production environments. Experimental features are not
 subject to the Node.js Semantic Versioning model.
 ```
 
-*Note*: Caution must be used when making use of `Experimental` features,
-particularly within modules that may be used as dependencies (or dependencies
-of dependencies) within a Node.js application. End users may not be aware that
-experimental features are being used, and therefore may experience unexpected
-failures or behavioral changes when changes occur. To help avoid such surprises,
-`Experimental` features may require a command-line flag to explicitly enable
-them, or may cause a process warning to be emitted. By default, such warnings
-are printed to `stderr` and may be handled by attaching a listener to the
-`process.on('warning')` event.
-
 ```txt
 Stability: 2 - Stable
 The API has proven satisfactory. Compatibility with the npm ecosystem
 is a high priority, and will not be broken unless absolutely necessary.
 ```
 
+*Note*: Caution must be used when making use of `Experimental` features,
+particularly within modules that may be used as dependencies (or dependencies
+of dependencies) within a Node.js application. End users may not be aware that
+experimental features are being used, and therefore may experience unexpected
+failures or behavior changes when API modifications occur. To help avoid such
+surprises, `Experimental` features may require a command-line flag to
+explicitly enable them, or may cause a process warning to be emitted.
+By default, such warnings are printed to [`stderr`][] and may be handled by
+attaching a listener to the [`process.on('warning')`][] event.
+
 ## JSON Output
+<!-- YAML
+added: v0.6.12
+-->
 
 > Stability: 1 - Experimental
 
-Every HTML file in the markdown has a corresponding JSON file with the
-same data.
-
-This feature was added in Node.js v0.6.12. It is experimental.
+Every `.html` document has a corresponding `.json` document presenting
+the same information in a structured manner. This feature is
+experimental, and added for the benefit of IDEs and other utilities that
+wish to do programmatic things with the documentation.
 
 ## Syscalls and man pages
 
 System calls like open(2) and read(2) define the interface between user programs
 and the underlying operating system. Node functions which simply wrap a syscall,
-like `fs.open()`, will document that. The docs link to the corresponding man
+like [`fs.open()`][], will document that. The docs link to the corresponding man
 pages (short for manual pages) which describe how the syscalls work.
 
-**Note:** some syscalls, like lchown(2), are BSD-specific. That means, for
-example, that `fs.lchown()` only works on macOS and other BSD-derived systems,
+Some syscalls, like lchown(2), are BSD-specific. That means, for
+example, that [`fs.lchown()`][] only works on macOS and other BSD-derived systems,
 and is not available on Linux.
 
 Most Unix syscalls have Windows equivalents, but behavior may differ on Windows
@@ -96,3 +95,7 @@ issue 4760](https://github.com/nodejs/node/issues/4760).
 
 [submit an issue]: https://github.com/nodejs/node/issues/new
 [the contributing guide]: https://github.com/nodejs/node/blob/master/CONTRIBUTING.md
+[`stderr`]: process.html#process_process_stderr
+[`process.on('warning')`]: process.html#process_event_warning
+[`fs.open()`]: fs.html#fs_fs_open_path_flags_mode_callback
+[`fs.lchown()`]: fs.html#fs_fs_lchown_path_uid_gid_callback

doc/api/fs.md

@@ -1099,7 +1099,7 @@ changes:
 * `path` {string|Buffer|URL}
 
 Synchronous version of [`fs.exists()`][].
-Returns `true` if the file exists, `false` otherwise.
+Returns `true` if the path exists, `false` otherwise.
 
 Note that `fs.exists()` is deprecated, but `fs.existsSync()` is not.
 (The `callback` parameter to `fs.exists()` accepts parameters that are

doc/api/synopsis.md

@@ -38,7 +38,7 @@ $ node example.js
 Server running at http://127.0.0.1:3000/
 ```
 
-All of the examples in the documentation can be run similarly.
+Many of the examples in the documentation can be run similarly.
 
 [Command Line Options]: cli.html#cli_command_line_options
 [web server]: http.html

doc/api/tty.md

@@ -12,9 +12,9 @@ However, it can be accessed using:
 const tty = require('tty');
 ```
 
-When Node.js detects that it is being run inside a text terminal ("TTY")
-context, the `process.stdin` will, by default, be initialized as an instance of
-`tty.ReadStream` and both `process.stdout` and `process.stderr` will, by
+When Node.js detects that it is being run with a text terminal ("TTY")
+attached, [`process.stdin`][] will, by default, be initialized as an instance of
+`tty.ReadStream` and both [`process.stdout`][] and [`process.stderr`][] will, by
 default be instances of `tty.WriteStream`. The preferred method of determining
 whether Node.js is being run within a TTY context is to check that the value of
 the `process.stdout.isTTY` property is `true`:
@@ -27,15 +27,16 @@ false
 ```
 
 In most cases, there should be little to no reason for an application to
-create instances of the `tty.ReadStream` and `tty.WriteStream` classes.
+manually create instances of the `tty.ReadStream` and `tty.WriteStream`
+classes.
 
 ## Class: tty.ReadStream
 <!-- YAML
 added: v0.5.8
 -->
 
-The `tty.ReadStream` class is a subclass of `net.Socket` that represents the
-readable side of a TTY. In normal circumstances `process.stdin` will be the
+The `tty.ReadStream` class is a subclass of [`net.Socket`][] that represents the
+readable side of a TTY. In normal circumstances [`process.stdin`][] will be the
 only `tty.ReadStream` instance in a Node.js process and there should be no
 reason to create additional instances.
 
@@ -52,7 +53,7 @@ raw device. Defaults to `false`.
 added: v0.5.8
 -->
 
-A `boolean` that is always `true`.
+A `boolean` that is always `true` for `tty.ReadStream` instances.
 
 ### readStream.setRawMode(mode)
 <!-- YAML
@@ -77,8 +78,8 @@ added: v0.5.8
 -->
 
 The `tty.WriteStream` class is a subclass of `net.Socket` that represents the
-writable side of a TTY. In normal circumstances, `process.stdout` and
-`process.stderr` will be the only `tty.WriteStream` instances created for a
+writable side of a TTY. In normal circumstances, [`process.stdout`][] and
+[`process.stderr`][] will be the only `tty.WriteStream` instances created for a
 Node.js process and there should be no reason to create additional instances.
 
 ### Event: 'resize'
@@ -130,3 +131,8 @@ added: v0.5.8
 The `tty.isatty()` method returns `true` if the given `fd` is associated with
 a TTY and `false` if it is not, including whenever `fd` is not a non-negative
 integer.
+
+[`net.Socket`]: net.html#net_class_net_socket
+[`process.stdin`]: process.html#process_process_stdin
+[`process.stdout`]: process.html#process_process_stdout
+[`process.stderr`]: process.html#process_process_stderr