Copyedit

content/en/docs/concepts/configuration/pod-priority-preemption.md

@@ -9,22 +9,24 @@ weight: 70
 
 {{% capture overview %}}
 
-{{< feature-state state="beta" >}}
+{{< feature-state for_k8s_version="1.8" state="alpha" >}}
+{{< feature-state for_k8s_version="1.11" state="beta" >}}
 
-[Pods](/docs/user-guide/pods) in Kubernetes 1.8 and later can have priority. Priority
-indicates the importance of a Pod relative to other Pods. When a Pod cannot be scheduled,
+[Pods](/docs/user-guide/pods) can have _priority_. Priority
+indicates the importance of a Pod relative to other Pods. If a Pod cannot be scheduled,
 the scheduler tries to preempt (evict) lower priority Pods to make scheduling of the
-pending Pod possible. In Kubernetes 1.9 and later, Priority also affects scheduling
+pending Pod possible.
+
+In Kubernetes 1.9 and later, Priority also affects scheduling
 order of Pods and out-of-resource eviction ordering on the Node.
 
 Pod priority and preemption are moved to beta since Kubernetes 1.11 and are enabled by default in
 this release and later.
 
-{{< note >}}
-**Note**: Pod priority and preemption were in alpha and not enabled by default in older versions of
-Kubernetes. To use these features in the older versions of Kubernetes, follow the instructions in the
-documentation for your Kubernetes version.
-{{< /note >}}
+In Kubernetes versions where Pod priority and preemption is still an alpha-level
+feature, you need to explicitly enable it. To use these features in the older versions of
+Kubernetes, follow the instructions in the documentation for your Kubernetes version, by
+going to the documentation archive version for your Kubernetes version.
 
 | Kubernetes Version | Priority and Preemption State | Enabled by default |
 | -------- |:-----:|:----:|
@@ -49,34 +51,35 @@ them from creating pods at high priorities. However, this feature is in alpha as
 ## How to use priority and preemption
 To use priority and preemption in Kubernetes 1.11 and later, follow these steps:
 
-1. Add one or more PriorityClasses.
+1. Add one or more [PriorityClasses](#priorityclass).
 
-1. Create Pods with `priorityClassName` set to one of the added PriorityClasses.
+1. Create Pods with[`priorityClassName`](#pod-priority) set to one of the added PriorityClasses.
 Of course you do not need to create the Pods directly; normally you would add 
 `priorityClassName` to the Pod template of a collection object like a Deployment.
 
-The following sections provide more information about these steps.
-
-You can create [PriorityClasses](#priorityclass)
-and create Pods with [`priorityClassName`](#pod-priority) set.
+Keep reading for more information about these steps.
 
 If you try the feature and then decide to disable it, you must remove the PodPriority
-command-line flag or set it to false, and then restart the API server and
+command-line flag or set it to `false`, and then restart the API server and
 scheduler. After the feature is disabled, the existing Pods keep their priority
-fields, but preemption is disabled, and priority fields are ignored, and you
-cannot set `priorityClassName` in new Pods.
+fields, but preemption is disabled, and priority fields are ignored. If the feature
+is disabled, you cannot set `priorityClassName` in new Pods.
 
 ## How to disable preemption
 
+{{< note >}}
 **Note**: In Kubernetes 1.11, critical pods (except DaemonSet pods, which are
 still scheduled by the DaemonSet controller) rely on scheduler preemption to be
 scheduled when a cluster is under resource pressure. For this reason, we do not
 recommend disabling this feature. If you still have to disable this feature,
 follow the instructions below.
-
-In Kubernetes 1.11 and later, preemption is controlled by a kube-scheduler flag `disablePreemption`, which is set to `false` by default.
+{{< /note >}}
+
+In Kubernetes 1.11 and later, preemption is controlled by a kube-scheduler flag
+`disablePreemption`, which is set to `false` by default.
 
-If you have to disable preemption, just set `disablePreemption` to true. This will keep pod priority enabled while preemption is disabled. Here is a sample configuration:
+To disable preemption, set `disablePreemption` to true. This keeps pod priority
+enabled but disables preemption. Here is a sample configuration:
 
 ```yaml
 apiVersion: componentconfig/v1alpha1
@@ -90,7 +93,8 @@ disablePreemption: true
 
 ```
 
-Please note: although preemption of scheduler is enabled by default, preemption will not happen if `PodPriority` feature is disabled.
+Although preemption of the scheduler is enabled by default, it is disabled if `PodPriority`
+feature is disabled.
 
 ## PriorityClass
 
@@ -113,22 +117,17 @@ with `globalDefault` set, the priority of Pods with no `priorityClassName` is ze
 The `description` field is an arbitrary string. It is meant to tell users of
 the cluster when they should use this PriorityClass.
 
-{{< note >}}
-**Note 1**: If you upgrade your existing cluster and enable this feature, the priority
-of your existing Pods will be considered to be zero.
-{{< /note >}}
+### Notes about PodPriority and existing clusters
+- If you upgrade your existing cluster and enable this feature, the priority
+of your existing Pods is effectively zero.
 
-{{< note >}}
-**Note 2**: Addition of a PriorityClass with `globalDefault` set to true does not
+- Addition of a PriorityClass with `globalDefault` set to `true` does not
 change the priorities of existing Pods. The value of such a PriorityClass is used only
 for Pods created after the PriorityClass is added.
-{{< /note >}}
 
-{{< note >}}
-**Note 3**: If you delete a PriorityClass, existing Pods that use the name of the
-deleted priority class remain unchanged, but you are not able to create more Pods
+- If you delete a PriorityClass, existing Pods that use the name of the
+deleted PriorityClass remain unchanged, but you cannot create more Pods
 that use the name of the deleted PriorityClass.
-{{< /note >}}
 
 ### Example PriorityClass