chore(docs): outline new feature stages (#14786)

EdwardAngert · web-flow · commit fe895cd65a9c · 2024-09-26T15:54:14.000-04:00
adds new feature sections ### To do - [x] populate or delete scope of support sections - [ ] if populate, then: - what should people expect - how/where do they get it - [x] rm Alpha? - [ ] ~link to wikipedia?~ - ~EA: <https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha>~ - ~Experimental: <https://en.wikipedia.org/wiki/Software_release_life_cycle#Feature-complete>~ - ~Beta: <https://en.wikipedia.org/wiki/Software_release_life_cycle#Open_and_closed_beta>~ --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
diff --git a/docs/contributing/feature-stages.md b/docs/contributing/feature-stages.md
@@ -1,21 +1,34 @@
 # Feature stages
 
-Some Coder features are released as Alpha or Experimental.
+Some Coder features are released in feature stages before they are generally
+available.
 
-## Alpha features
+If you encounter an issue with any Coder feature, please submit a
+[GitHub issues](https://github.com/coder/coder/issues) or join the
+[Coder Discord](https://discord.gg/coder).
 
-Alpha features are enabled in all Coder deployments but the feature is subject
-to change, or even be removed. Breaking changes may not be documented in the
-changelog. In most cases, features will only stay in alpha for 1 month.
+## Early access features
 
-We recommend using [GitHub issues](https://github.com/coder/coder/issues) to
-leave feedback and get support for alpha features.
+Early access features are neither feature-complete nor stable. We do not
+recommend using early access features in production deployments.
+
+Coder releases early access features behind an “unsafe” experiment, where
+they’re accessible but not easy to find.
 
 ## Experimental features
 
 These features are disabled by default, and not recommended for use in
 production as they may cause performance or stability issues. In most cases,
-features will only stay in experimental for 1-2 weeks of internal testing.
+experimental features are complete, but require further internal testing and
+will stay in the experimental stage for one month.
+
+Coder may make significant changes to experiments or revert features to a
+feature flag at any time.
+
+If you plan to activate an experimental feature, we suggest that you use a
+staging deployment.
+
+You can opt-out of an experiment after you've enabled it.
 
 ```yaml
 # Enable all experimental features
@@ -27,7 +40,7 @@ coder server --experiments=feature1,feature2
 # Alternatively, use the `CODER_EXPERIMENTS` environment variable.
 ```
 
-## Available experimental features
+### Available experimental features
 
 <!-- Code generated by scripts/release/docs_update_experiments.sh. DO NOT EDIT. -->
 <!-- BEGIN: available-experimental-features -->
@@ -37,3 +50,14 @@ coder server --experiments=feature1,feature2
 | `notifications` | Sends notifications via SMTP and webhooks following certain events. | mainline, stable |
 
 <!-- END: available-experimental-features -->
+
+## Beta
+
+Beta features are open to the public, but are tagged with a `Beta` label.
+
+They’re subject to minor changes and may contain bugs, but are generally ready
+for use.
+
+## General Availability (GA)
+
+All other features have been tested, are stable, and are enabled by default.
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -1,7 +1,5 @@
 {
-	"versions": [
-		"main"
-	],
+	"versions": ["main"],
 	"routes": [
 		{
 			"title": "About",
@@ -419,10 +417,7 @@
 					"description": "Learn how to use the role based access control against templates",
 					"path": "./admin/rbac.md",
 					"icon_path": "./images/icons/rbac.svg",
-					"state": [
-						"enterprise",
-						"beta"
-					]
+					"state": ["enterprise", "beta"]
 				},
 				{
 					"title": "Configuration",
