Updated language and active voice.

Signed-off-by: John Krug <john.krug@suse.com>

docs/explanations/architecture.md

@@ -20,18 +20,18 @@ This language must generate a WebAssembly binary for Kubewarden to use.
 ## What _is_ a policy?
 
 A policy is an [Open Container Initiative](https://opencontainers.org/) (OCI)
-artifact containing a WebAssembly module,
+artifact. It contains a WebAssembly module,
 the policy code, and the metadata required by PolicyServer
-performing admission request validations and mutations.
+to perform admission request validations and mutations.
 
 :::note
 
-In the same manner as
+Like
 [Kubernetes](https://kubernetes.io/docs/contribute/style/style-guide/),
 Kubewarden uses the terms
 'PolicyServer' when discussing the Kubewarden policy server
 and
-`policy-server` when discussing Pod or Deployment of a Kubewarden PolicyServer.
+`policy-server` when discussing a Pod or Deployment of a Kubewarden PolicyServer.
 
 :::
 
@@ -48,47 +48,48 @@ The project utilizes a combination of:
 - Webhooks (Validation and Mutating)
 - the Control Plane's event notification system
 
-### Effectively uses Kubernetes architecture
+### Makes effective use of the Kubernetes architecture
 
-Kubewarden operates seamlessly within the Kubernetes ecosystem.
-At its core, the Kubewarden controller is a Kubernetes controller,
-monitoring Kubewarden Custom Resource Definitions (CRDs)
-and configuring Kubernetes resources to execute them.
-This integration ensures that Kubewarden uses the built-in Kubernetes mechanisms,
-such as controllers and CRDs, to watch, manage, and apply security policies efficiently.
+Kubewarden operates seamlessly within the Kubernetes ecosystem. At its core,
+the Kubewarden controller is a Kubernetes controller, monitoring Kubewarden
+Custom Resource Definitions (CRDs) and configuring Kubernetes resources to
+execute them. This integration ensures that Kubewarden uses the built-in
+Kubernetes mechanisms, such as controllers and CRDs, to watch, manage, and
+apply security policies efficiently.
 
 ### Extensible policy definition
 
-Kubewarden employs CRDs to define and manage Kubewarden resources,
-which specify the rules for admission request validations.
-This design enables users to extend Kubernetes' capabilities with custom admission controls,
-ensuring that security and compliance policy enforcement is consistent across the cluster.
+Kubewarden employs CRDs to define and manage Kubewarden resources, which
+specify the rules for admission request validations. This design enables users
+to extend Kubernetes' capabilities with custom admission controls, so
+that security and compliance policy enforcement is consistent across the
+cluster.
 
 ### Direct admission control
 
-When setup by the Kubewarden controller,
-the policy-server Service receives admission requests directly from the Kubernetes control plane,
-using `ValidationWebhooks` and `MutatingWebhooks`.
-This direct interaction streamlines the admission control process,
-reducing latency and increasing efficiency in policy enforcement.
-
-WebAssembly offers a sand-boxed execution environment,
-ensuring policies run in isolation,
-thus enhancing the security and stability of the policy enforcement mechanism.
-This isolation prevents policies from interfering with each other or with the host system,
-mitigating the risk of malicious code execution.
-WebAssembly is portable and efficient,
-enabling policies to run across different environments without modification.
-This cross-platform compatibility ensures that Kubewarden policies are versatile,
-and can be distributed and executed in diverse Kubernetes clusters
+When setup by the Kubewarden controller, the policy-server Service receives
+admission requests directly from the Kubernetes control plane, using
+`ValidationWebhooks` and `MutatingWebhooks`. This direct interaction
+streamlines the admission control process, reducing latency and increasing
+efficiency in policy enforcement.
+
+WebAssembly offers a sand-boxed execution environment, ensuring policies run in
+isolation, thus enhancing the security and stability of the policy enforcement
+mechanism. This isolation prevents policies from interfering with each other or
+with the host system, mitigating the risk of malicious code execution.
+WebAssembly is portable and efficient, enabling policies to run across
+different environments without modification.
+
+This cross-platform compatibility ensures that Kubewarden policies are
+versatile, so you can distribute and run them on diverse Kubernetes clusters
 
 ### OCI based policy artifacts
 
 Policies in Kubewarden are OCI (Open Container Initiative) artifacts.
-This standardization makes the distribution and versioning of policies easier,
+This standardization makes the distribution and versioning of policies easier.
 Policies contain both the WebAssembly modules for enforcement logic,
 and metadata necessary for the PolicyServer's operation.
-Leveraging OCI artifacts promotes interoperability and ease of management
+Using OCI artifacts promotes interoperability and ease of management
 within cloud ecosystems.
 
 ### Fine-grained policy application
@@ -110,7 +111,8 @@ The Kubewarden consists of these components:
   Kubewarden integrates with Kubernetes using
   [Dynamic Admission Control](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/).
   In particular, Kubewarden operates as a Kubernetes Admission Webhook.
-  The `policy-server` is the Webhook endpoint called by the Kubernetes API server to validate requests.
+  The `policy-server` is the Webhook endpoint called by the Kubernetes
+  API server to validate requests.
 
 - The [Kubewarden controller](https://github.com/kubewarden/kubewarden-controller)
   is a Kubernetes controller that reconciles Kubewarden's Custom Resources.
@@ -137,7 +139,7 @@ The Kubewarden consists of these components:
 
   [Audit scanner](/explanations/audit-scanner/audit-scanner.md)
   constantly checks the resources declared in the cluster,
-  flagging the ones that no longer adhere with the deployed Kubewarden policies.
+  flagging the ones that no longer adhere to the deployed Kubewarden policies.
 
   ```mermaid
   %%{
@@ -227,7 +229,7 @@ a reconciliation loop activates in `kubewarden-controller`,
 for the `policy-server` owning the policy.
 This reconciliation loop creates a `ConfigMap` with all the policies bound to the `policy-server`.
 Then the Deployment rollout of the `policy-server` starts.
-It results in starting the new `policy-server` instance with the updated configuration.
+This results in starting the new `policy-server` instance with the updated configuration.
 
 At start time, the `policy-server` reads its configuration from the ConfigMap
 and downloads all the Kubewarden policies specified.
@@ -243,8 +245,8 @@ There is further documentation in the
 [specification reference](../reference/spec/01-intro-spec.md)
 section of the documentation.
 
-If one or more policies received wrong configuration parameters,
-from the policy specification provided by the user,
+If any policies received wrong configuration parameters,
+from the users policy specification,
 then any admission requests evaluated by that policy return an error.
 
 When Kubewarden has configured all policies,
@@ -309,7 +311,7 @@ A cluster can have many PolicyServers and Kubewarden policies defined.
 There are benefits of having many PolicyServers:
 
 - You can isolate noisy namespaces or tenants,
-  those generating many policy evaluations,
+  or those generating many policy evaluations,
   from the rest of the cluster so as not to adversely affect other cluster operations.
 
 - You can run mission-critical policies in a dedicated PolicyServer pool,

docs/explanations/certificates.md

@@ -13,42 +13,44 @@ doc-topic: [explanations, certificates]
   <link rel="canonical" href="https://docs.kubewarden.io/explanations/certificates"/>
 </head>
 
-Since Kubewarden v1.17.0, the cert-manager dependency was removed. The
+Kubewarden v1.17.0 removed the cert-manager dependency. The
 controller is able to manage all the certificates used by all the components.
-This means that the controller has a new reconciliation loop that ensures the
+Now, the controller has a new reconciliation loop that ensures the
 certificates are always up-to-date and the webhook configuration is correct.
 
-The first certificate generation is done by the Helm chart installation. It
-will generate the root CA with ten years until expiration. The Helm chart
-installation also generates the controller webhook webserver certificate,
-signed by the root CA. This is used by the API server to communicate with the
+The Helm chart installation does the first certificate generation. It
+generates the root CA with ten years until expiration. The Helm chart
+installation also generates the controller webhook web server certificate,
+signed by the root CA. The API server use this to communicate with the
 Kubewarden controller to validate the CRDs. It has a one year expiration.
 
 Once the controller starts, its reconciler renews the certificates
-automatically when they are about to expire. It also updates all the
+automatically when they're about to expire. It also updates the
 certificates and webhook configurations used by the entire Kubewarden stack.
 
 :::note
 All the certificates generated by the Helm chart and later by the controller uses
 ECDSA P256 keys.
 :::
 
-The reconciliation loop renews certificates 60 days before expiration. The
-certificates are rotated without downtime.
-The reconciliation loop takes care of renewing the root CA too. 60 days before
-its expiration, a new root CA is generated and the CA bundled used by all the
-webhooks is updated with one that includes both the new root CA and
-the old one.
-The change of the root CA leads the reconciler to recreate the certificates
-issued to the webhooks.
-The propagation of the new certificates requires some time. However during this
-time the updated CA bundle allows the API server to continue to communicate
-with all the webhooks without any downtime.
-
-Once the new certificate is ready and the old one is invalid, the controller
-will update the CA bundle used by the webhooks to include only the latest root CA.
-
-When a policy server certificate or the controller webserver certificate is
-renewed, the controller updates the secret with the new certificate signed by
+The reconciliation loop renews certificates 60 days before expiration.
+Certificates rotate without downtime. The reconciliation loop takes care of
+renewing the root CA too.
+
+The controller generates a new root CA 60 days before expiration. The
+controller updates the CA bundle used by all the webhooks to include both the
+new root CA and the old one.
+
+The change of the root CA leads the reconciler to re-create the certificates
+issued to the webhooks. The propagation of the new certificates requires a
+period of time. However, during this time the updated CA bundle lets the API
+server continue to communicate with all the webhooks without any downtime.
+
+When a new certificate is ready, and the old one is invalid, the controller
+updates the CA bundle, used by webhooks, to include only the latest root
+CA.
+
+When a policy server, or controller web server certificate
+renews, the controller updates the secret with the new certificate signed by
 the root CA. Due to this reload feature, the controller, and the policy server,
 use the new certificate with no need to restart processes, hence no downtime.

docs/explanations/context-aware-policies.md

@@ -15,23 +15,29 @@ doc-topic: [explanations, context-aware-policies]
 
 Developers can create policies that fetch information from a Kubernetes cluster at run time.
 These are context aware policies.
-Context aware policies can determine whether an `AdmissionRequest` is acceptable using information from resources deployed in the cluster.
+Context aware policies can determine whether an `AdmissionRequest` is
+acceptable using information from resources deployed in the cluster.
 
 :::note
 Context aware policies are only available in Kubewarden versions ≥ v1.6.0.
 :::
 
-Resources a policy can access in the cluster is controlled by the policy server's [Service Account](https://kubernetes.io/docs/concepts/security/service-accounts/).
+Control of which resources a policy can access in the cluster is by the policy server's
+[Service Account](https://kubernetes.io/docs/concepts/security/service-accounts/).
 A cluster administrator controls what a policy can access via Kubernetes RBAC rules.
 Context aware policies have only **read** access to the requested resources.
 
 For security reasons, only `ClusterAdmissionPolicy` policies can fetch information from the Kubernetes cluster.
-This is because `AdmissionPolicy` resources can be deployed by unprivileged users.
-If a context aware policy is deployed as an `AdmissionPolicy` all attempts to access Kubernetes resources are blocked and reported to the cluster administrator.
+This is because unprivileged users can deploy `AdmissionPolicy` resources.
+
+If an unprivileged user deploys a context aware policy as an `AdmissionPolicy`, the system:
+
+- Blocks all attempts to access Kubernetes resources.
+- Reports them to the cluster administrator.
 
 By default, all the cluster resources are blocked.
 A Kubewarden administrator defines which Kubernetes resources each context aware policy is allowed to read.
-This is done in the `ClusterAdmissionPolicy` definition using the field `contextAwareResources` .
+The `ClusterAdmissionPolicy` definition uses the field `contextAwareResources` to do this.
 
 The following example deploys a policy that requires access to the `Deployment` and `Pod` resources:
 
@@ -63,7 +69,7 @@ spec:
 Once deployed, this policy can read the data of the `deployment` and `pod` resources.
 
 Policy authors provide lists of Kubernetes resources for their context aware policy.
-This is done by annotating the policy.
+Policy authors do this by annotating the policy.
 Kubewarden administrators view policy metadata using the `kwctl inspect` command.
 They can get a list of resources the policy needs access to.
 An administrator uses this list to populate the `ClusterAdmissionPolicy` definition.
@@ -74,19 +80,19 @@ To prevent system abuse, Kubewarden administrators must review the resources the
 For example, a policy evaluating ingress objects would have good reasons to read the `Ingress` resources defined in the cluster.
 The same policy can't justify having access to `Secret` resources.
 
-Policies should have the least access needed to function correctly.
+Policies should have the minimum access needed to function correctly.
 
 :::
 
 :::note
 
-Kubernetes resources are identified by `apiVersion` and `kind`.
+Kubernetes resource identification uses `apiVersion` and `kind`.
 
 Usually, `apiVersion` is a string in the format `<api>/<version>`.
-Resources from the `core` API group (Pod, Service, and others) should not define the group name, `<api>`.
+Resources from the `core` API group (Pod, Service, and others) shouldn't define the group name, `<api>`.
 They should only define the `<version>` (for example, `v1`).
 
-For a core resource, the first will not work, the second will.
+For a core resource, the first won't, the second will.
 
 ```console
 - apiVersion: "core/v1"
@@ -104,5 +110,6 @@ All other Kubernetes resources need the full definition: `<api>/<version>`.
 
 ## Further readings
 
-More detailed information about context aware policies can be found in [this section](../reference/spec/05-context-aware-policies.md)
-of our reference documentation.
+You can find more detailed information about context aware policies in
+[this section](../reference/spec/05-context-aware-policies.md)
+of the reference documentation.