Review Remarks

site/content/en/docs/concepts/_index.md

@@ -42,8 +42,7 @@ This priority value from a `WorkloadPriorityClass` is only used for managing the
 
 ### [Admission Check](/docs/concepts/admission_check)
 
-A mechanism allowing custom internal or external components to control the timing of
-workloads admission.
+A mechanism allowing internal or external components to influence the timing of workloads admission.
 
 ![Components](/images/queueing-components.svg)
 
@@ -58,7 +57,7 @@ Is the process during which the kueue scheduler locks the resources needed by a
 ### Admission
 
 The process of admitting a Workload to start (Pods to be created). A Workload
-is admitted when it has a Quota Reservation and all it's potential [AdmissionCheckStates](/docs/concepts/admission_check)
+is admitted when it has a Quota Reservation and all its [AdmissionCheckStates](/docs/concepts/admission_check)
 are `Ready`.
 
 ### [Cohort](/docs/concepts/cluster_queue#cohort)

site/content/en/docs/concepts/admission_check.md

@@ -3,28 +3,27 @@ title: "Admission Check"
 date: 2023-10-05
 weight: 6
 description: >
-  A mechanism allowing custom internal or external components to control the timing of
+  A mechanism allowing internal or external components to influence the timing of
   workloads admission.
 ---
 
-## Components
-
-### Admission Check
-
-Admission check is a none namespaced API object used to define details about an `AdmissionCheck` like:
+AdmissionChecks are a mechanism that allows Kueue to consider additional criteria before admitting a Workload.
+When a ClusterQueue has AdmissionChecks configured, each of the checks has to provide a
+positive signal to the Workload before it can be [Admitted](docs/concepts/#admission).
 
-#### controllerName
-
-Is the name with which controller identifies with, not necessarily a K8S Pod or Deployment name. Cannot be empty.
+## Components
 
-#### retryDelayMinutes
+You can configure the mechanism using the following components:
 
-Specifies how long to keep the workload suspended after a failed check (after it transitioned to False). After that the check state goes to "Unknown". The default is 15 min.
+### Admission Check
 
-#### parameters
+Admission check is a non-namespaced API object used to define details about an `AdmissionCheck` like:
 
-Identifies the resource providing additional check parameters.
+- **controllerName** - It's an identifier for the controller that processes this AdmissionCheck, not necessarily a Kubernetes Pod or Deployment name. Cannot be empty.
+- **retryDelayMinutes** - Specifies how long to keep the workload suspended after a failed check (after it transitioned to False). After that the check state goes to "Unknown". The default is 15 min.
+- **parameters** - Identifies an additional resource providing additional parameters for the check.
 
+An AdmissionCheck object looks like the following:
 ```yaml
 apiVersion: kueue.x-k8s.io/v1beta1
 kind: AdmissionCheck
@@ -41,13 +40,16 @@ spec:
 
 ### ClusterQueue admissionChecks
 
-Once defined an AdmissionCheck can be referenced in the ClsterQueues Spec resulting in all Workloads associated with the queue needing to be evaluated by its controller before being admitted. Similarly with `ResourceFalvors`, if an `AdmissionCheck` is not found or its controller has not mark it as `Active`, the cluster queue will be marked as Inactive.
+Once defined, an AdmissionCheck can be referenced in the ClusterQueues' spec. All Workloads associated with the queue need to be evaluated by the AdmissionCheck's controller before being admitted.
+Similarly to `ResourceFlavors`, if an `AdmissionCheck` is not found or its controller has not mark it as `Active`, the cluster queue will be marked as Inactive.
 
 ### AdmissionCheckState
 
-AdmissionCheckState is the way the way the state of an AdmissionCkeck for a specific Workload is tracked.
+AdmissionCheckState is the way the state of an AdmissionCkeck for a specific Workload is tracked.
+
+AdmissionCheckStates are listed in the Workload's `.status.admissionCheckStates` field.
 
-It is following the schema:
+The status of a Workload that has pending AdmissionChecks looks like the following:
 ```yaml
 properties:
   lastTransitionTime:
@@ -97,7 +99,7 @@ type: object
 
 A list of states being maintained in the Status of all the monitored Workloads.
 
-Kueue ensurers that the list of the Workloads AdmissionCheckStates is in sync with the list of its associated ClusterQueue, new checks being added with the `Pending` state.
+Kueue ensures that the list of the Workloads AdmissionCheckStates is in sync with the list of its associated ClusterQueue, Kueue adds new checks with the `Pending` state.
 
 - Once a workload has QuotaReservation and all its AdmissionChecks are in "Ready" state it will become Admitted.
 - If at least one of the Workloads AdmissionCheck is in the `Retry` state.
@@ -107,9 +109,8 @@ Kueue ensurers that the list of the Workloads AdmissionCheckStates is in sync wi
   - If `Admitted` the workload is evicted.
   - If the workload has `QuotaReservation` it will be release released.
   - The workload is marked as 'Finished' with a relevant failure message.
-- `PreemptionRequired` is a state specific to PreemptionPolicies, from an Admission point of view being synonym to `Pending`
 
 ### Admission Check Controller
 
 Is a component that monitors Workloads maintaining the content of its specific `AdmissionCheckStates` and the `Active` condition of the `AdmissionCheck`s  its  controlling.
-The logic based on which an `AdmissionCheck` changes states in not in the scope of Kueue.
+The logic for how an `AdmissionCheck` changes states is not part of Kueue.

site/static/examples/sample-admission-check.yaml

@@ -11,7 +11,6 @@ spec:
 
 ---
 
-
 apiVersion: kueue.x-k8s.io/v1beta1
 kind: ProvisioningRequestConfig
 metadata: