docs: audit popular pages

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>

Author: Iheanacho-ai

public/kubernetes-guides/cni/deploying-cilium.mdx

@@ -18,24 +18,26 @@ It is easy and automatic.
 
 ## Storage clusters
 
-> **Sidero Labs** recommends having separate disks (separate from the Talos install disk) dedicated for storage.
+Sidero Labs recommends having separate disks (separate from the Talos install disk) dedicated for storage.
 
 Redundancy, scaling capabilities, reliability, speed, maintenance load, and ease of use are all factors you must consider when managing your own storage.
 
 Running a storage cluster can be a very good choice when managing your own storage.
 The following projects are known to work with Talos Linux and provide good options, depending on your situation.
 
-**Mayastor**: Ultra-low latency and high-performance workloads.
+- **Mayastor**: Ultra-low latency and high-performance workloads.
 
-**Longhorn**: Simple, reliable, easy-to-use Kubernetes storage with easy replication and snapshots.
+- **Longhorn**: Simple, reliable, easy-to-use Kubernetes storage with easy replication and snapshots.
 
-**Rook/Ceph**: Enterprise-scale, distributed, multi-tenant storage (block, file, and object storage)
+- **Rook/Ceph**: Enterprise-scale, distributed, multi-tenant storage (block, file, and object storage)
 
 Also, if you need _both_ mount-once _and_ mount-many capabilities, Ceph is your answer.
 
-> Please note that _most_ people should not use mount-many semantics.
-> NFS is pervasive because it is old and easy, _not_ because it is a good idea.
-> There are all manner of locking, performance, change control, and reliability concerns inherent in _any_ mount-many situation, so we **strongly** recommend you avoid this method.
+<Note>
+Please note that _most_ people should not use mount-many semantics.
+NFS is pervasive because it is old and easy, _not_ because it is a good idea.
+There are all manner of locking, performance, change control, and reliability concerns inherent in _any_ mount-many situation, so we **strongly** recommend you avoid this method.
+</Note>
 
 ### Longhorn
 
@@ -96,29 +98,32 @@ Follow the Post-Installation from official [documentation](https://openebs.io/do
 
 ### Piraeus / LINSTOR
 
-* [Piraeus-Operator](https://piraeus.io/)
-* [LINSTOR](https://linbit.com/drbd/)
-* [DRBD Extension](https://github.com/siderolabs/extensions#storage)
+[Piraeus](https://piraeus.io/) is a Kubernetes storage solution built on top of [LINSTOR](https://linbit.com/drbd/) and DRBD. It provides replicated block storage with low overhead and is a solid choice for clusters where performance and reliability matter. To use it with Talos, you will also need the [DRBD extension](https://github.com/siderolabs/extensions#storage).
 
 #### Install Piraeus Operator V2
 
-There is already a how-to for Talos: [Link](https://piraeus.io/docs/stable/how-to/talos/)
+Piraeus maintains a dedicated how-to guide for Talos that covers the full installation process, including the necessary Talos-specific configuration. Follow it [here](https://piraeus.io/docs/stable/how-to/talos/) before proceeding.
 
-#### Create first storage pool and PVC
+#### Create a storage pool and PVC
 
-Before proceeding, install linstor plugin for kubectl:
-https://github.com/piraeusdatastore/kubectl-linstor
+Once the operator is installed, you will need the `linstor` plugin for `kubectl` to manage storage resources. Install it directly from the [kubectl-linstor repository](https://github.com/piraeusdatastore/kubectl-linstor), or via [krew](https://krew.sigs.k8s.io/):
 
-Or use [krew](https://krew.sigs.k8s.io/): `kubectl krew install linstor`
+```sh
+kubectl krew install linstor
+```
+
+With the plugin in place, create a device pool on a blank disk (one with no existing partition table) on your target node:
 
 ```sh
-# Create device pool on a blank (no partition table!) disk on node01
-kubectl linstor physical-storage create-device-pool --pool-name nvme_lvm_pool LVM node01 /dev/nvme0n1 --storage-pool nvme_pool
+kubectl linstor physical-storage create-device-pool \
+  --pool-name nvme_lvm_pool LVM node01 /dev/nvme0n1 \
+  --storage-pool nvme_pool
 ```
 
-piraeus-sc.yml
+Next, define a StorageClass that uses the pool you just created. Save the following as `piraeus-sc.yml`:
 
 ```yaml
+cat <<EOF > piraeus-sc.yml
 apiVersion: storage.k8s.io/v1
 kind: StorageClass
 metadata:
@@ -129,10 +134,12 @@ parameters:
   linstor.csi.linbit.com/storagePool: nvme_pool
 provisioner: linstor.csi.linbit.com
 volumeBindingMode: WaitForFirstConsumer
+EOF
 ```
 
+Then apply it:
+
 ```sh
-# Create storage class
 kubectl apply -f piraeus-sc.yml
 ```
 

public/kubernetes-guides/csi/storage.mdx

@@ -63,7 +63,7 @@ as:
 
 <CodeBlock lang="sh">
 {`
-  $ talosctl upgrade --nodes 10.20.30.40 \\
+  talosctl upgrade --nodes 10.20.30.40 \\
   --image ghcr.io/siderolabs/installer:${release_v1_12}
 `}
 </CodeBlock>

public/talos/v1.12/configure-your-talos-cluster/lifecycle-management/upgrading-talos.mdx

@@ -1,6 +1,5 @@
 ---
 title: Quickstart
-weight: 20
 description: "A short guide on setting up a simple Talos Linux cluster locally with Docker."
 ---
 
@@ -10,7 +9,7 @@ import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx"
 
 import { release_v1_12, k8s_release } from '/snippets/custom-variables.mdx';
 
-The easiest way to run Talos is by using the CLI (`talosctl`) to create a cluster on a machine with `docker` installed.
+This guide walks you through spinning up a local Talos Linux cluster using Docker and `talosctl` in a few minutes.
 
 <iframe width="560"
     height="315"
@@ -20,58 +19,54 @@ The easiest way to run Talos is by using the CLI (`talosctl`) to create a cluste
     encrypted-media; gyroscope;
     picture-in-picture;
     web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen
-    >
-</iframe>
+    > </iframe>
 
-### Prerequisites
+## Prerequisites
 
-#### `talosctl`
+Before you begin, make sure you have the following tools installed:
 
-Download `talosctl` (macOS or Linux):
+- `talosctl`: On macOS or Linux, install `talosctl` by running the command below. For other systems, see the [talosctl documentation](./talosctl):
 
-```bash
-brew install siderolabs/tap/talosctl
-```
+    ```bash
+    brew install siderolabs/tap/talosctl
+    ```
 
-#### `kubectl`
+- `kubectl`: Refer to the [Install kubectl documentation](https://kubernetes.io/docs/tasks/tools/install-kubectl/) for installation instructions.
 
-Download `kubectl` via one of the methods outlined in the [documentation](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
+## Create the cluster
 
-### Create the cluster
+With your prerequisites in place, run the following command to create a cluster on Docker:
 
-Now run the following:
-
-```bash
+````bash
 talosctl cluster create docker
-```
+````
 
 <Note>
-If you are using Docker Desktop on a macOS computer, if you encounter the error: *Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?* you may need to manually create the link for the Docker socket:
-```sudo ln -s "$HOME/.docker/run/docker.sock" /var/run/docker.sock```
-
+If you are using Docker Desktop on macOS and encounter the error: *Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?*, you may need to manually create the Docker socket symlink:
+````sudo ln -s "$HOME/.docker/run/docker.sock" /var/run/docker.sock```
 </Note>
 
-You can explore using Talos API commands:
+Once the cluster is up, verify that you can reach Kubernetes by running:
 
 ```bash
-talosctl dashboard --nodes 10.5.0.2
+kubectl get nodes -o wide
 ```
 
-Verify that you can reach Kubernetes:
+You should see output similar to the following:
 
 <CodeBlock lang="sh">
-{`
-kubectl get nodes -o wide
-
-NAME                           STATUS   ROLES    AGE    VERSION          INTERNAL-IP   EXTERNAL-IP   OS-IMAGE                 KERNEL-VERSION   CONTAINER-RUNTIME
-talos-default-controlplane-1   Ready    master   115s   v${k8s_release}   10.5.0.2      <none>        Talos ${release_v1_12}   <host kernel>    containerd://1.5.5
-talos-default-worker-1         Ready    <none>   115s   v${k8s_release}   10.5.0.3      <none>        Talos ${release_v1_12}   <host kernel>    containerd://1.5.5
-`}
+{` NAME                           STATUS   ROLES    AGE    VERSION          INTERNAL-IP   EXTERNAL-IP   OS-IMAGE                 KERNEL-VERSION   CONTAINER-RUNTIME\ntalos-default-controlplane-1   Ready    master   115s   v${k8s_release}   10.5.0.2      <none>        Talos ${release_v1_12}   <host kernel>    containerd://2.1.5\ntalos-default-worker-1         Ready    <none>   115s   v${k8s_release}   10.5.0.3      <none>        Talos ${release_v1_12}   <host kernel>    containerd://2.1.5 `}
 </CodeBlock>
 
-### Destroy the cluster
+From here, you can explore the Talos API using `talosctl`:
+
+```bash
+talosctl --help
+```
+
+## Destroy the cluster
 
-When you are all done, remove the cluster:
+When you are done, run the following command to tear down the cluster and clean up all associated resources:
 
 ```bash
 talosctl cluster destroy

public/talos/v1.12/getting-started/quickstart.mdx

@@ -8,8 +8,12 @@ import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx"
 
 <VersionWarningBanner />
 
+This page outlines the system requirements for running Talos Linux. Requirements are listed for both control plane and worker nodes, and are broadly similar to those of Kubernetes.
+
 ## Minimum requirements
 
+The following are the minimum system requirements for running Talos Linux on control plane and worker nodes:
+
 <table>
   <thead>
     <tr>
@@ -35,7 +39,9 @@ import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx"
   </tbody>
 </table>
 
-## Recommended
+## Recommended requirements
+
+For production or heavier workloads, the following specifications are recommended:
 
 <table>
   <thead>
@@ -62,12 +68,10 @@ import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx"
   </tbody>
 </table>
 
-These requirements are similar to that of Kubernetes.
-
-## Storage
+## Storage requirement
 
-Talos Linux itself only requires less than 100 MB of disk space, but the EPHEMERAL partition is used to store pulled images, container work directories, and so on. Thus a minimum of 10 GiB of disk space is required. 100 GiB is recommended.
+While Talos Linux itself requires less than 100 MB of disk space, the EPHEMERAL partition is used to store pulled images, container working directories, and other runtime data — so a minimum of 10 GiB of total disk space is required, with 100 GiB recommended.
 
-Talos manages disk partitioning automatically during installation, creating EFI, META, STATE, and EPHEMERAL partitions. The EPHEMERAL partition then expands to fill all the space left after the first three. That space can either remain entirely with EPHEMERAL or be divided into additional user volumes, depending on your needs. See [Disk Layout](../configure-your-talos-cluster/storage-and-disk-management/disk-management#disk-layout) for details.
+During installation, Talos automatically manages disk partitioning, creating EFI, META, STATE, and EPHEMERAL partitions. The EPHEMERAL partition expands to fill all remaining space after the first three partitions. That space can either remain entirely with EPHEMERAL or be divided into additional user volumes, depending on your needs. See [Disk Layout](../configure-your-talos-cluster/storage-and-disk-management/disk-management#disk-layout) for details.
 
-For production, it is often more efficient to dedicate a smaller disk for the Talos installation itself, and use additional disks for workload storage. Using a large, single disk for both system and workloads is supported, but may not be optimal depending on your environment.
+For production environments, it is often more efficient to dedicate a smaller disk to the Talos installation and use separate disks for workload storage. Using a single large disk for both system and workloads is supported, but may not be optimal depending on your setup.

public/talos/v1.12/getting-started/system-requirements.mdx

@@ -7,37 +7,34 @@ import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx"
 
 <VersionWarningBanner />
 
-## Recommended
+Use `talosctl` to interact with the Talos API, manage nodes, and configure your Talos machines. Follow the instructions below to install it on your operating system.
 
-The client can be installed and updated via the [Homebrew package manager](https://brew.sh/) for macOS and Linux.
-You will need to install `brew` and then you can install `talosctl` from the Sidero Labs tap.
+## Linux and macOS
+
+The recommended way to install `talosctl` on Linux and macOS is via the [Homebrew package manager](https://brew.sh/). This method automatically keeps `talosctl` up to date as new versions are released, without any manual intervention.
 
 ```bash
 brew install siderolabs/tap/talosctl
 ```
 
-This will also keep your version of `talosctl` up to date with new releases.
-This homebrew tap also has formulae for `omnictl` if you need to install that package.
+The same Homebrew tap also includes a formula for `omnictl`.
 
-> Note: Your `talosctl` version should match the version of Talos Linux you are running on a host.
-> To install a specific version of `talosctl` with `brew` you can follow [this github issue](https://github.com/siderolabs/homebrew-tap/issues/75).
+<Note>Your `talosctl` version should match the version of Talos Linux running on your host. To install a specific version of `talosctl` with Homebrew, refer to [this GitHub issue](https://github.com/siderolabs/homebrew-tap/issues/75) for guidance.</Note>
 
 ## Alternative install
 
-You can automatically install the correct version of `talosctl` for your operating system and architecture with an installer script.
-This script won't keep your version updated with releases and you will need to re-run the script to download a new version.
+If Homebrew is not available in your environment, you can use the installer script to automatically download the correct version of `talosctl` for your operating system and architecture:
 
 ```bash
 curl -sL https://talos.dev/install | sh
 ```
 
-This script will work on macOS, Linux, and WSL on Windows.
-It supports amd64 and arm64 architecture.
+This script supports macOS, Linux, and WSL on Windows, and works on both amd64 and arm64 architectures.
 
-## Manual and Windows install
+Note that this method does not update automatically, you will need to re-run the script to install a newer version.
 
-All versions can be manually downloaded from the [talos releases page](https://github.com/siderolabs/talos/releases/) including Linux, macOS, and Windows.
+## Windows
 
-You will need to add the binary to a folder part of your executable `$PATH` to use it without providing the full path to the executable.
+For Windows, all `talosctl` releases can be downloaded manually from the [Talos releases page](https://github.com/siderolabs/talos/releases/), which includes binaries for Linux, macOS, and Windows.
 
-Updating the binary will be a manual process.
+Once downloaded, add the binary to a folder on your `$PATH` so you can run it without specifying the full path to the executable. As with the alternative install method, updating `talosctl` on Windows is a manual process.

public/talos/v1.12/getting-started/talosctl.mdx

@@ -7,19 +7,17 @@ import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx"
 
 <VersionWarningBanner />
 
-Talos can be installed on bare-metal machine using an ISO image.
-ISO images for `amd64` and `arm64` architectures are available on the [Talos releases page](https://github.com/siderolabs/talos/releases/latest/).
+Talos can be installed on bare-metal machines using an ISO image. ISO images for `amd64` and `arm64` architectures are available on the [Talos releases page](https://github.com/siderolabs/talos/releases/latest/).
 
-Talos doesn't install itself to disk when booted from an ISO until the machine configuration is applied.
+When booted from an ISO, Talos does not install itself to disk until a machine configuration is applied.
 
-Please follow the [getting started guide](../../getting-started/getting-started) for the generic steps on how to install Talos.
+For steps on how to install Talos, follow the [getting started guide](../../getting-started/getting-started).
 
-> Note: If there is already a Talos installation on the disk, the machine will boot into that installation when booting from a Talos ISO.
-> The boot order should prefer disk over ISO, or the ISO should be removed after the installation to make Talos boot from disk.
+<Note>If a Talos installation already exists on the disk, the machine will boot into that installation even when booting from a Talos ISO. The boot order should prefer disk over ISO, or the ISO should be removed after installation to ensure Talos boots from disk.</Note>
 
-See [kernel parameters reference](../../reference/kernel) for the list of kernel parameters supported by Talos.
+See the [kernel parameters reference](../../reference/kernel) for a list of kernel parameters supported by Talos.
 
-There are two flavors of ISO images available:
+Two flavors of ISO image are available:
 
-* `metal-<arch>.iso` supports booting on BIOS and UEFI systems (for x86, UEFI only for arm64)
-* `metal-<arch>-secureboot.iso` supports booting on only UEFI systems in SecureBoot mode (via [Image Factory](../../learn-more/image-factory))
+* `metal-<arch>.iso` supports booting on BIOS and UEFI systems (UEFI only for arm64)
+* `metal-<arch>-secureboot.iso` supports booting on UEFI systems in SecureBoot mode only (via [Image Factory](../../learn-more/image-factory))

public/talos/v1.12/platform-specific-installations/bare-metal-platforms/iso.mdx

@@ -94,7 +94,7 @@ as:
 
 <CodeBlock lang="sh">
 {`
-  $ talosctl upgrade --nodes 10.20.30.40 \\
+  talosctl upgrade --nodes 10.20.30.40 \\
   --image ghcr.io/siderolabs/installer:${release_v1_13}
 `}
 </CodeBlock>