Address comments

docs/src/capi/explanation/capi-ck8s.md

@@ -63,9 +63,9 @@ clusters it manages, such as a public cloud or an on-premises data centre. It
 serves as a centralised location for managing the configuration, policies, and
 security of multiple managed clusters. By leveraging the management cluster,
 users can easily create and manage a fleet of Kubernetes clusters in a
-consistent and repeatable manner. Although it's also possible to maintain the
-CAPI providers in the workload cluster (or any secondary cluster). 
-Read more about this in the [upstream docs around pivoting].
+consistent and repeatable manner. While CAPI providers mostly live on the 
+management cluster, it's also possible to maintain the them in the workload 
+cluster. Read more about this in the [upstream docs around pivoting].
 
 The {{product}} team maintains the two providers required for integrating with CAPI:
 
@@ -97,4 +97,4 @@ The {{product}} team maintains the two providers required for integrating with C
 
 <!-- LINKS -->
 [tutorial section]: ./tutorial
-[Pivot section]: https://cluster-api.sigs.k8s.io/clusterctl/commands/move#pivot
+[upstream docs around pivoting]: https://cluster-api.sigs.k8s.io/clusterctl/commands/move#pivot

docs/src/capi/howto/custom-ck8s.md

@@ -21,7 +21,7 @@ details on the required setup.
 
 This guide will call the generated cluster spec manifest `cluster.yaml`.
 
-## Using config spec
+## Using the configuration specification
 
 {{product}} can be installed on machines using a specific `channel`, 
 `revision` or `localPath` by specifying the respective field in the spec 
@@ -31,7 +31,7 @@ of the machine.
 spec:
   ...
   spec:
-    channel: 1.32-classic/candidate
+    channel: 1.xx-classic/candidate
     # Or
     revision: 1234
     # Or
@@ -67,9 +67,9 @@ Now the new control plane nodes that are created using this manifest will have
 the `1.31-classic/candidate` {{product}} snap installed on them!
 
 ```{note}
-If you're only interested in installing a specific channel, revision, or 
-form the local path, it's recommended to 
-[use the config spec](#using-config-spec).
+[Use the configuration specification](#using-config-spec), 
+if you're only interested in installing a specific channel, revision, or 
+form the local path.
 ```
 
 <!-- LINKS -->

docs/src/capi/howto/migrate-management.md

@@ -2,7 +2,7 @@
 
 Management cluster migration allows admins to move the management cluster 
 to a different substrate or perform maintenance tasks without disruptions.
-This guide will walk you through the migration of a management cluster.
+This guide walks you through the migration of a management cluster.
 
 ## Prerequisites
 
@@ -13,8 +13,7 @@ installed and configured.
 
 Before migrating a cluster, ensure that both the target and source management 
 clusters run the same version of providers (infrastructure, bootstrap, 
-control plane). To do so, `clusterctl init` should be called against the 
-target cluster:
+control plane). Use `clusterctl init` to target the cluster::
 
 ```
 clusterctl get kubeconfig <provisioned-cluster> > targetconfig

docs/src/capi/howto/upgrade-providers.md

@@ -5,12 +5,12 @@ providers of a management cluster.
 
 ## Prerequisites
 
-- A {{product}} CAPI management cluster with providers installed and 
-configured.
+- A {{product}} CAPI management cluster with installed and 
+configured providers.
 
 ## Check for updates
 
-With `clusterctl`, check if there are any new versions of the running 
+Check whether there are any new versions of your running 
 providers:
 
 ```

docs/src/capi/tutorial/getting-started.md

@@ -16,7 +16,7 @@ curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.9.3/
 sudo install -o root -g root -m 0755 clusterctl /usr/local/bin/clusterctl
 ```
 
-For more `clusterctl` versions head to the [upstream release page][clusterctl-release-page].
+For more `clusterctl` versions refer to the [upstream release page][clusterctl-release-page].
 
 ## Set up a management cluster
 
@@ -59,7 +59,7 @@ sudo mv clusterawsadm /usr/local/bin
 
 `clusterawsadm` helps you bootstrapping the AWS environment that CAPI will use.
 It will also create the necessary IAM roles for you. For more `clusterawsadm` 
-versions head to the [upstream release page][clusterawsadm-release-page].
+versions refer to the [upstream release page][clusterawsadm-release-page].
 
 Start by setting up environment variables defining the AWS account to use, if
 these are not already defined: