From 939f3ebd7e49f70fd6aeeaeaff7d389cf35114f3 Mon Sep 17 00:00:00 2001
From: Tim Bannister <tim@scalefactory.com>
Date: Tue, 12 Nov 2019 02:08:06 +0000
Subject: [PATCH] Expand feature gates page (#17535)

* Tidy feature gate metadata

* Tweak feature gate headings

Use sentence case where appropriate

* Add feature gate explanation for GA

* Add what's next section to feature gate page

* Signpost readers to explanation of feature gate stages
---
 .../feature-gates.md                          | 35 ++++++++++++-------
 1 file changed, 23 insertions(+), 12 deletions(-)

diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md
index 25bf2937ac..15966fc7a0 100644
--- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md
+++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md
@@ -1,5 +1,4 @@
 ---
-title: Feature Gates
 weight: 10
 title: Feature Gates
 content_template: templates/concept
@@ -8,15 +7,20 @@ content_template: templates/concept
 {{% capture overview %}}
 This page contains an overview of the various feature gates an administrator
 can specify on different Kubernetes components.
+
+See [feature stages](#feature-stages) for an explanation of the stages for a feature.
 {{% /capture %}}
 
 {{% capture body %}}
 ## Overview
 
-Feature gates are a set of key=value pairs that describe alpha or experimental
-features.
-An administrator can use the `--feature-gates` command line flag on each component
-to turn a feature on or off. Each component supports a set of feature gates unique to that component.
+Feature gates are a set of key=value pairs that describe Kubernetes features.
+You can turn these features on or off using the `--feature-gates` command line flag
+on each Kubernetes component.
+
+
+Each Kubernetes component lets you enable or disable a set of feature gates that
+are relevant to that component.
 Use `-h` flag to see a full set of feature gates for all components.
 To set feature gates for a component, such as kubelet, use the `--feature-gates` flag assigned to a list of feature pairs:
 
@@ -32,9 +36,11 @@ different Kubernetes components.
 - The "Until" column, if not empty, contains the last Kubernetes release in which
   you can still use a feature gate.
 - If a feature is in the Alpha or Beta state, you can find the feature listed
-  in the Alpha/Beta feature gate table.
-- If a feature is stable (GA) or deprecated, you can find all stages for that feature listed
-  in the GA/Deprecated feature gate table.
+  in the [Alpha/Beta feature gate table](#feature-gates-for-alpha-or-beta-features).
+- If a feature is stable you can find all stages for that feature listed in the
+  [Graduated/Deprecated feature gate table](#feature-gates-for graduated-or-deprecated-features).
+- The [Graduated/Deprecated feature gate table](#feature-gates-for graduated-or-deprecated-features).
+  also lists deprecated and withdrawn features.
 
 ### Feature gates for Alpha or Beta features
 
@@ -240,9 +246,9 @@ different Kubernetes components.
 | `VolumeSubpath` | `true` | GA | 1.13 | - |
 {{< /table >}}
 
-## Using a Feature
+## Using a feature
 
-### Feature Stages
+### Feature stages
 
 A feature can be in *Alpha*, *Beta* or *GA* stage.
 An *Alpha* feature means:
@@ -273,12 +279,13 @@ Please do try *Beta* features and give feedback on them!
 After they exit beta, it may not be practical for us to make more changes.
 {{< /note >}}
 
-A *GA* feature is also referred to as a *stable* feature. It means:
+A *General Availability* (GA) feature is also referred to as a *stable* feature. It means:
 
+* The feature is always enabled; you cannot disable it.
 * The corresponding feature gate is no longer needed.
 * Stable versions of features will appear in released software for many subsequent versions.
 
-### Feature Gates
+## List of feature gates {#feature-gates}
 
 Each feature gate is designed for enabling/disabling a specific feature:
 
@@ -443,3 +450,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `WinOverlay`: Allows kube-proxy to run in overlay mode for Windows.
 
 {{% /capture %}}
+{{% capture whatsnext %}}
+* The [deprecation policy](/docs/reference/using-api/deprecation-policy/) for Kubernetes explains
+  the project's approach to removing features and components.
+{{% /capture %}}