Review docs pages (#1011)

docs/canonicalk8s/index.md

@@ -16,7 +16,7 @@ development and innovation without having to worry about the infrastructure.
 
 Whether you are deploying a small cluster to get accustomed to Kubernetes or a
 huge enterprise level deployment across the globe, {{product}} can cater to
-your needs. If would like to jump straight in, head to the
+your needs. If you would like to jump straight in, head to the
 [snap getting started tutorial!](src/snap/tutorial/getting-started.md)
 
 ![Illustration depicting working on components and clouds][logo]

docs/src/snap/explanation/about.md

@@ -3,16 +3,15 @@
 At its core, {{product}} is a full implementation of upstream
 [Kubernetes] delivered in a compact, secure, reliable [snap] package. As the
 upstream Kubernetes services are not all that is required for a fully
-functional cluster, additional services and features are built in. You can
-deploy the snap and have a single-node cluster up and running in minutes.
+functional cluster, additional services and features are built in.
 
 ## Why a snap?
 
 Snaps are self-contained, simple to install, secure, cross-platform, and
 dependency-free. They can be installed on any Linux system which supports the
 `snapd` service (see the [snapd documentation] for more information). Security
-and robustness are their key features, alongside being easy to install, easy to
-maintain and easy to upgrade.
+and robustness are their key features, alongside being easy to install,
+maintain and upgrade.
 
 ## What else comes with it?
 
@@ -41,8 +40,8 @@ method] page to see which method best suits your project's needs.
 
 Yes. {{product}} is designed to be eminently scalable. You can start
 with a single node and add more as and when the need arises. Scale up or down
-at any time. Systems with more than three nodes will automatically become
-Highly Available.
+at any time. Systems with more than three control plane nodes will automatically
+become Highly Available.
 
 ## Does it come with support?
 

docs/src/snap/howto/install/lxd.md

@@ -32,8 +32,8 @@ wget https://raw.githubusercontent.com/canonical/k8s-snap/main/tests/integration
 ```
 <!-- markdownlint-restore -->
 
-```{note} For an explanation of the settings in this file, [see below]
-(explain-rules)
+```{note} For an explanation of the settings in this file,
+[see below](explain-rules)
 ```
 
 To pipe the content of the file into the k8s LXD profile, run:
@@ -107,7 +107,7 @@ you can access it via the LXD container’s IP address. This can be done using
 `k8s kubectl expose`. This example will expose the deployment’s port 80 to a
 port assigned by Kubernetes.
 
-In this example, we will use [Microbot] as it provides a simple HTTP endpoint
+We will use [Microbot] as it provides a simple HTTP endpoint
 to expose. These steps can be applied to any other deployment.
 
 First, initialise the k8s cluster with
@@ -129,7 +129,7 @@ Then check that the deployment has come up.
 lxc exec k8s -- sudo k8s kubectl get all
 ```
 
-...should return output similar to:
+...should return an output similar to:
 
 <!-- markdownlint-disable -->
 ```
@@ -194,10 +194,14 @@ And it can be permanently removed with:
 lxc delete k8s
 ```
 
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
 (explain-rules)=
-
 ## Explanation of custom LXD rules
 
+
+<!-- markdownlint-restore -->
+
 **linux.kernel_modules**: Comma separated list of kernel modules to load before
 starting the container
 

docs/src/snap/howto/install/offline.md

@@ -302,8 +302,8 @@ by running the command:
 sudo k8s bootstrap --address MY-NODE-IP
 ```
 
-Add and remove nodes as described in the
-[add-and-remove-nodes tutorial][nodes].
+Adding nodes requires the same steps to be repeated but instead of
+bootstrapping you would need to join the node to the cluster.
 
 After a while, confirm that all the cluster nodes show up in the output of the
 `sudo k8s kubectl get node` command.

docs/src/snap/reference/community.md

@@ -3,12 +3,12 @@
 This rapidly growing community is a diverse bunch of people - developers,
 Kubernetes admins, inventors, researchers, students… and we all share the joy
 of a reliable, flexible, secure, timely version of upstream Kubernetes. The
-team recognise the important role each and every user plays in the success of
+team recognizes the important role each and every user plays in the success of
 the project as a whole and how valuable your contributions are.
 
 ## Do you have questions?
 
-Do you have questions about {{product}}? Perhaps you want some ideas
+Do you have questions about {{product}}? Perhaps you want to share some ideas
 on how to best achieve a certain goal or maybe some aspect of your Kubernetes
 doesn't behave the way you expect. Perhaps you'd just like some advice from
 more experienced users. There are a number of ways to get in touch:

docs/src/snap/tutorial/add-remove-nodes.md

@@ -10,13 +10,13 @@ the foundational aspects of clustering using {{product}} without the
 complexities of a full-scale, production setup. If your nodes are already
 installed, you can skip the Multipass setup and go to [step 2](step2).
 
-## Before starting
+## Before we begin
 
 In this tutorial, "**control plane**" refers to the Multipass VM that operates
 the control plane, while "**worker**" denotes the Multipass VM running the
 worker node.
 
-## What you will need
+## Prerequisites
 
 - Multipass (See [Multipass Installation][Multipass Installation])
 
@@ -33,7 +33,6 @@ multipass launch 22.04 --name worker -m 4G -c 4 -d 8G
 ```
 
 This step can take a few minutes as Multipass creates the new virtual machines.
-It's normal and expected.
 
 Once the virtual machine has been created, you can run commands on it by
 opening a shell. For example:
@@ -58,16 +57,16 @@ Install {{product}} on both VMs with the following command:
 ### 2. Bootstrap your control plane node
 
 <!-- markdownlint-restore -->
+
+{{product}} allows you to create two types of nodes: control plane and
+worker nodes. In this example, we just initialise a control plane node.
+
 Bootstrap the control plane node with default configuration:
 
 ```
 sudo k8s bootstrap
 ```
 
-{{product}} allows you to create two types of nodes: control plane and
-worker nodes. In this example, we just initialised a control plane node, now
-let's create a worker node.
-
 Generate the token required for the worker node to join the cluster by executing
 the following command on the control-plane node:
 
@@ -125,9 +124,10 @@ It is important to clean-up your nodes before tearing down the VMs.
 
 Keep in mind the consequences of removing nodes:
 
-```{warning} Do not remove the leader node.
-If you have less than 3 nodes and you remove any node you will lose availability
-   of your cluster.
+```{warning} If you have less than 3 control plane nodes the cluster
+is not in high availability mode. In such a setup the first node, ie the node you called
+`k8s bootstrap` on, plays the role of the leader. If you remove the leader
+you will lose availability of your cluster.
 ```
 
 To tear down the entire cluster, execute:

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

@@ -51,34 +51,22 @@ should run:
 sudo k8s status
 ```
 
-It may take a few moments for the cluster to be ready. Confirm that {{product}}
-has transitioned to the `cluster status ready` state by running:
-
 ```{important}
 By default, the command waits a few minutes before timing out.
-On a very slow network connection, this default timeout might be insufficient, resulting in a "Context cancelled" error.
-In that case, you can either increase the timeout using the `--timeout` flag or re-run the command to
+On a very slow network connection, this default timeout might be insufficient,
+resulting in a "Context cancelled" error. In that case, you can either increase
+the timeout using the  `--timeout` flag or re-run the command to
 continue waiting until the cluster is ready.
 ```
 
-```
-sudo k8s status --wait-ready
-```
+It may take a few moments for the cluster to be ready. Use `k8s status` to wait
+for {{product}} to get to a `cluster status ready` state by running:
 
-Run the following command to list all the pods in the `kube-system`
-namespace:
 
 ```
-sudo k8s kubectl get pods -n kube-system
+sudo k8s status --wait-ready
 ```
 
-You will observe at least three pods running. The functions of these three pods
-are:
-
-- **CoreDNS**: Provides DNS resolution services.
-- **Network operator**: Manages the life-cycle of the networking solution.
-- **Network agent**: Facilitates network management.
-
 ### 5. Access Kubernetes
 
 The standard tool for deploying and managing workloads on Kubernetes
@@ -97,6 +85,21 @@ sudo k8s kubectl get nodes
 sudo k8s kubectl get services
 ```
 
+Run the following command to list all the pods in the `kube-system`
+namespace:
+
+```
+sudo k8s kubectl get pods -n kube-system
+```
+
+You will observe at least three pods running. The functions of these three pods
+are:
+
+- **CoreDNS**: Provides DNS resolution services.
+- **Network operator**: Manages the life-cycle of the networking solution.
+- **Network agent**: Facilitates network management.
+
+
 ### 6. Deploy an app
 
 Kubernetes is meant for deploying apps and services.

docs/src/snap/tutorial/kubectl.md

@@ -17,7 +17,7 @@ Before you begin, make sure you have the following:
 The `kubectl` command communicates with the
 [Kubernetes API server][kubernetes-api-server].
 
-{{product}} includes a `kubectl` which is built from the
+{{product}} includes `kubectl`, built from the
 original upstream source into the `k8s` snap you have installed and is
 configured to work with the cluster out of the box.