Add 'about these docs' section

diff --git a/doc/api/_toc.markdown b/doc/api/_toc.markdown
index ec37a57..4e67106 100644 (file)
--- a/doc/api/_toc.markdown
+++ b/doc/api/_toc.markdown
@@ -1,5 +1,4 @@
-## Table of Contents
-
+* [About these Docs](documentation.html)
 * [Synopsis](synopsis.html)
 * [Globals](globals.html)
 * [STDIO](stdio.html)

diff --git a/doc/api/all.markdown b/doc/api/all.markdown
index 8b5ae25..47a818f 100644 (file)
--- a/doc/api/all.markdown
+++ b/doc/api/all.markdown
@@ -1,3 +1,4 @@
+@include documentation
 @include synopsis
 @include globals
 @include stdio

diff --git a/doc/api/documentation.markdown b/doc/api/documentation.markdown
new file mode 100644 (file)
index 0000000..d3c7a86
--- /dev/null
+++ b/doc/api/documentation.markdown
@@ -0,0 +1,59 @@
+# About this Documentation
+
+<!-- type=misc -->
+
+The goal of this documentation is to comprehensively explain the Node.js
+API, both from a reference as well as a conceptual point of view.  Each
+section describes a built-in module or high-level concept.
+
+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
+`.markdown` file in the `doc/api/` folder in node's source tree.  The
+documentation is generated using the `tools/doc/generate.js` program.
+The HTML template is located at `doc/template.html`.
+
+## Stability Index
+
+<!--type=misc-->
+
+Throughout the documentation, you will see indications of a section's
+stability.  The Node.js API is still somewhat changing, and as it
+matures, certain parts are more reliable than others.  Some are so
+proven, and so relied upon, that they are unlikely to ever change at
+all.  Others are brand new and experimental, or known to be hazardous
+and in the process of being redesigned.
+
+The notices look like this:
+
+    Stability: 1 Experimental
+
+The stability indices are as follows:
+
+* **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.
+
+* **1 - Experimental**  This feature was introduced recently, and may change
+or be removed in future versions.  Please try it out and provide feedback.
+If it addresses a use-case that is important to you, tell the node core team.
+
+* **2 - Unstable**  The API is in the process of settling, but has not yet had
+sufficient real-world testing to be considered stable. Backwards-compatibility
+will be maintained if reasonable.
+
+* **3 - Stable**  The API has proven satisfactory, but cleanup in the underlying
+code may cause minor changes.  Backwards-compatibility is guaranteed.
+
+* **4 - API Frozen**  This API has been tested extensively in production and is
+unlikely to ever have to change.
+
+* **5 - Locked**  Unless serious bugs are found, this code will not ever
+change.  Please do not suggest changes in this area; they will be refused.