doc: update experimental status to reflect use

* Update the experimental status to reflect actual common use.
* Also make a few formatting fixes.

Fixes: https://github.com/nodejs/node/issues/12701

PR-URL: https://github.com/nodejs/node/pull/12723
Fixes: https://github.com/nodejs/node/issues/12701
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>

doc/api/documentation.md

@@ -39,17 +39,29 @@ The stability indices are as follows:
 
 ```txt
 Stability: 0 - Deprecated
-This feature is known to be problematic, and changes are
-planned.  Do not rely on it.  Use of the feature may cause warnings.  Backwards
-compatibility should not be expected.
+This feature is known to be problematic, and changes may be planned. Do
+not rely on it. Use of the feature may cause warnings to be emitted.
+Backwards compatibility across major versions should not be expected.
 ```
 
 ```txt
 Stability: 1 - Experimental
-This feature is subject to change, and is gated by a command line flag.
-It may change or be removed in future versions.
+This feature is still under active development and subject to non-backwards
+compatible changes, or even removal, in any future version. Use of the feature
+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
@@ -72,7 +84,7 @@ 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
 pages (short for manual pages) which describe how the syscalls work.
 
-**Caveat:** some syscalls, like lchown(2), are BSD-specific. That means, for
+**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,
 and is not available on Linux.