Refactor documentation for Buildkite setup: improve clarity, consistency, and formatting across multiple files.

Author: madeline-underwood

content/learning-paths/servers-and-cloud-computing/buildkite-gcp/buildkite-agent-setup.md

@@ -1,5 +1,5 @@
 ---
-title: Set-up Buildkite
+title: Set up Buildkite
 weight: 5
 
 ### FIXED, DO NOT MODIFY
@@ -10,21 +10,24 @@ layout: learningpathall
 
 After installing the Buildkite agent binary on a Google Axion C4A Arm VM, you can set up and configure a Buildkite agent and queue.
 
-## 1. Create an Agent Token
+## Create an agent token
 
 Before configuring the agent, you need an agent token from your Buildkite organization.
 
-1. Log in to your Buildkite account (you can login with GitHub), and go to your Organization Settings
-2. Click Agents in the left menu
-3. Click Create Agent Token  
-4. Enter a name for your token, such as `buildkite-arm`
-5. Click Create Token
-6. Copy the token immediately, you won’t be able to see it again after leaving the page.
+To create an agent token, follow these steps:
 
-![Buildkite Dashboard alt-text#center](images/agent-token.png "Create Buildkite agent Token")
+- Sign in to your Buildkite account. You can use your GitHub credentials if you prefer.
+- In the left menu, select **Organization settings**.
+- Select **Agents**.
+- Select **Create agent token**.
+- Enter a descriptive name for the token, such as `buildkite-arm`.
+- Select **Create token**.
+- Copy the token and store it securely as you won’t be able to view it again after you leave the page.
 
+![Buildkite Dashboard alt-text#center](images/agent-token.png "Create Buildkite agent token")
 
-## 2. Configure Buildkite Agent
+
+## Configure Buildkite Agent
 
 Create the configuration directory and file on your local system with the commands below:
 
@@ -35,10 +38,10 @@ tags="queue=buildkite-queue1"
 EOF
 ```
 
-Replace `YOUR_AGENT_TOKEN` with the token you generated from your Buildkite Agents page.  
+Replace `YOUR_AGENT_TOKEN` with the token that you generated from your Buildkite Agents page.  
 
-{{% notice Note %}}
-You find it easier to copy the commands above into a text file named `config-agent.sh` and run the file.
+{{% notice Tip %}}
+You might find it easier to copy the commands above into a text file named `config-agent.sh` and run the file.
 ```console
 bash ./config-agent.sh
 ```
@@ -63,21 +66,23 @@ token="YOUR-GENERATED-TOKEN-VALUE"
 tags="queue=buildkite-queue1"
 ```
 
-## 3. Create a Queue in Buildkite
+## Create a Queue in Buildkite
 
 Now that your agent is created, you can create a queue. 
 
-1. Go to your Buildkite Organization select Queues and then select Create Queue
-2. Name the queue, for example `buildkite-queue1`
-3. Save the queue
+- Go to your Buildkite organization, select **Queues**, and then select **Create queue**.
+- Enter a name for the queue, for example `buildkite-queue1`.
+- Select **Save** to create the queue.
+
+This step connects your agent to the correct queue, ensuring jobs are routed to your Arm-based Buildkite agent.
 
 {{% notice Note %}}
 Make sure the queue name matches the `tags` field in the agent configuration.
 {{% /notice %}}
 
 ![Buildkite Dashboard alt-text#center](images/queue.png "Create Buildkite Queue")
 
-## 4. Verify the agent in the Buildkite UI
+## Verify the agent in the Buildkite UI
 
 First, start the agent on your local computer: 
 
@@ -91,6 +96,6 @@ Go Buildkite and select Agents
 
 Confirm that the agent is online and connected to the queue `buildkite-queue1`.
 
-![Buildkite Dashboard alt-text#center](images/agent.png "Verify Agent")
+![Buildkite Dashboard alt-text#center](images/agent.png "Verify the agent")
 
 The Buildkite agent is ready, you can proceed to use Buildkite for building multi-arch images. 

content/learning-paths/servers-and-cloud-computing/buildkite-gcp/installation.md

@@ -86,7 +86,8 @@ The Buildkite Agent version 3.43.0 introduces Linux/Arm64 Docker image for the B
 
 The [Arm Ecosystem Dashboard](https://developer.arm.com/ecosystem-dashboard/) recommends Buildkite Agent version v3.43.0 or later for Arm platforms.
 {{% /notice %}}
-### Install Docker
+
+## Install Docker
 
 Buildkite uses Docker to build and push images.
 
@@ -141,9 +142,13 @@ For more examples and ideas, visit:
 Docker Buildx is a plugin that allows the building of multi-architecture images, for example `arm64` and `amd64`. 
 If you're using SUSE Linux, you need to install Docker Buildx manually. On Ubuntu, Docker Buildx is included by default, so you can skip this step.
 
+For more information or troubleshooting details, see the [Docker Buildx documentation](https://docs.docker.com/build/buildx/).
+
 ## Download Docker Buildx
 
-Download the Docker Buildx binary and move it to the Docker CLI plugin directory. This enables advanced multi-architecture builds on your Arm VM.
+If you need to download Docker Buildx, follow these steps.
+
+Start by downloading the Docker Buildx binary and move it to the Docker CLI plugin directory. This enables advanced multi-architecture builds on your Arm VM:
 
 ```console
 wget https://github.com/docker/buildx/releases/download/v0.26.1/buildx-v0.26.1.linux-arm64

content/learning-paths/servers-and-cloud-computing/buildkite-gcp/instance.md

@@ -8,12 +8,13 @@ layout: learningpathall
 
 ## Get started
 
-You're about to launch a Google Axion C4A Arm virtual machine on Google Cloud Platform (GCP). This section guides you through each step, from selecting the optimal instance type to configuring your operating system and networking. By the end, you'll have a ready-to-use Arm-based VM, perfect for high-performance workloads and cloud-native development.
-You'll learn how to provision a Google Axion C4A Arm virtual machine on Google Cloud Platform (GCP) using the `c4a-standard-4` instance type with 4 vCPUs and 16 GB memory in the Google Cloud Console.
+You're about to launch a Google Axion C4A Arm virtual machine on Google Cloud Platform (GCP). This section guides you through each step, from selecting the optimal instance type to configuring your operating system and networking. 
 
-## Provision a VM
+By the end, you'll have a ready-to-use Arm-based VM, perfect for high-performance workloads and cloud-native development. Specifically, you'll learn how to provision a Google Axion C4A Arm virtual machine on Google Cloud Platform (GCP) using the `c4a-standard-4` instance type with 4 vCPUs and 16 GB memory in the Google Cloud Console.
 
-To create a virtual machine based on the C4A instance type:
+## Provision a virtual machine
+
+To create a virtual machine based on the C4A instance type, follow these steps:
 - Open the [Google Cloud Console](https://console.cloud.google.com/).
 - In the left navigation pane, select **Compute Engine** > **VM instances**.
 - Select **Create instance**.
@@ -22,13 +23,14 @@ To create a virtual machine based on the C4A instance type:
    - Select a **Region** and **Zone**.
    - For **Series**, select **C4A**.
    - For **Machine type**, select **c4a-standard-4**.
-- The following image shows the **Machine configuration** section with the C4A series and c4a-standard-4 machine type selected.
 
-   ![Screenshot of the Machine configuration section in Google Cloud Console with C4A series and c4a-standard-4 machine type selected.](images/gcp-vm.png "Creating a Google Axion C4A Arm virtual machine in Google Cloud Console")
+The following image shows the **Machine configuration** section with the C4A series and c4a-standard-4 machine type selected:
+
+   ![Screenshot of the Machine configuration section in Google Cloud Console with C4A series and c4a-standard-4 machine type selected.alt-text #center](images/gcp-vm.png "Creating a Google Axion C4A Arm virtual machine in Google Cloud Console")
 
 - In the **OS and storage** section, select **Change**.
    - In the **Operating system** dialog, choose an Arm64-based image such as **SUSE Linux Enterprise Server** or **Ubuntu**.
-   - Select your preferred version, making sure to choose the Arm architecture.
+   - Select your preferred version, making sure you select the Arm architecture.
    - Select **Select** to confirm your choice.
 - In the **Networking** section, enable the **Allow HTTP traffic** option.
 - Select **Create** to launch your instance.

content/learning-paths/servers-and-cloud-computing/buildkite-gcp/validation.md

@@ -10,7 +10,7 @@ layout: learningpathall
 
 Follow the steps below to run your pipeline on an Arm-based Buildkite agent. You will use Docker Buildx to create a multi-architecture image for both `arm64` and `amd64`. 
 
-### Ensure the agent is running
+## Ensure the agent is running
 
 Before your pipeline can execute, the Buildkite agent must be running and connected to your Buildkite account. To verify the agent status, run the following command on your VM:
 
@@ -20,15 +20,15 @@ sudo /root/.buildkite-agent/bin/buildkite-agent status
 
 This command checks the current state of your Buildkite agent and displays its connection status. When the agent is properly running and connected, you'll see logs indicating "Registered agent" in the output, confirming that the agent is online and ready to receive jobs from Buildkite. The agent continuously listens for new pipeline jobs and executes the steps you've defined in your configuration.
 
-### Trigger the pipeline
+## Trigger the pipeline
 
 To start your pipeline, navigate to your pipeline in the Buildkite web interface. From your Buildkite dashboard, select the pipeline you created and click the "New Build" button. Choose the branch you want to build from the dropdown menu, then click "Start Build" to begin execution.
 
 ![Buildkite Dashboard alt-text#center](images/build-p.png "Trigger the pipeline")
 
 When you trigger the pipeline, Buildkite sends the job to your Arm-based agent and begins executing the steps defined in your YAML configuration file. The agent will process each step in sequence, starting with Docker login, followed by creating the Buildx builder, and finally building and pushing your multi-architecture Docker image.
 
-### Monitor the Build
+## Monitor the Build
 
 You can see the logs of your build live in the Buildkite UI.
 
@@ -39,13 +39,13 @@ The steps include:
 
 ![Buildkite Dashboard alt-text#center](images/log.png "Monitor the build")
 
-### Verify Multi-Arch Image
+## Verify multi-arch image
 
 After the pipeline completes successfully, you can go to Docker Hub and verify the pushed multi-arch images:
 
 ![Docker-Hub alt-text#center](images/multi-arch-image.png "Figure 3: Docker image")
 
-### Run the Flask Application on Arm
+## Run the Flask application
 
 ```console
 docker pull <DOCKER_USERNAME>/multi-arch-app:latest
@@ -61,6 +61,11 @@ http://<VM_IP>
 ```
 You should see output similar to:
 
-![Buildkite Dashboard alt-text#center](images/browser.png "Figure 4: Verify Docker Images")
+![Buildkite Dashboard alt-text#center](images/browser.png "Verify Docker i
+mages")
 
 Your pipeline is working, and you have successfully built and ran the Flask application using your Arm-based Buildkite agent.
+
+## Recap your progress
+
+You've now completed the key steps to run a Buildkite pipeline on an Arm-based Google Axion C4A VM. You verified your agent connection, triggered and monitored a multi-architecture build, and successfully deployed and tested a Flask application in a Docker container. This workflow demonstrates how to use Arm infrastructure for modern CI/CD pipelines and multi-architecture container builds. Great work, you're now ready to apply these skills to your own Arm-based projects!