Enhance Buildkite documentation: improve clarity, section titles, and instructions for setting up agents and pipelines on Google Axion C4A Arm VMs.

Author: madeline-underwood

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

@@ -1,14 +1,14 @@
 ---
-title: Set up Buildkite
+title: Set up and connect Buildkite agent on a Google Axion C4A Arm VM
 weight: 5
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-# Set up a Buildkite agent
+## What you'll do in this section
 
-After installing the Buildkite agent binary on a Google Axion C4A Arm VM, you can set up and configure a Buildkite agent and queue.
+In this section, you'll configure and connect a Buildkite agent on a Google Axion C4A Arm virtual machine (VM). You'll generate an agent token, set up the agent configuration, create a Buildkite queue, and verify that your agent is online and ready to run CI/CD jobs on Arm infrastructure.
 
 ## Create an agent token
 
@@ -27,7 +27,7 @@ To create an agent token, follow these steps:
 ![Buildkite Dashboard alt-text#center](images/agent-token.png "Create Buildkite agent token")
 
 
-## Configure Buildkite Agent
+## Configure the Buildkite agent
 
 Create the configuration directory and file on your local system with the commands below:
 
@@ -66,7 +66,7 @@ token="YOUR-GENERATED-TOKEN-VALUE"
 tags="queue=buildkite-queue1"
 ```
 
-## Create a Queue in Buildkite
+## Create a queue in Buildkite
 
 Now that your agent is created, you can create a queue. 
 
@@ -80,7 +80,7 @@ This step connects your agent to the correct queue, ensuring jobs are routed to
 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")
+![Buildkite Dashboard alt-text#center](images/queue.png "Create the Buildkite queue")
 
 ## Verify the agent in the Buildkite UI
 
@@ -90,12 +90,13 @@ First, start the agent on your local computer:
 sudo /root/.buildkite-agent/bin/buildkite-agent start --build-path="/var/lib/buildkite-agent/builds"
 ```
 
-Then, confirm it is visible in the Buildkite UI:
+Then, confirm the agent is visible in the Buildkite UI, by doing the following:
 
-Go Buildkite and select Agents
+- In the Buildkite dashboard, select **Agents** from the left menu. This page lists all registered agents for your organization. 
+- Look for your new agent in the list and verify that its status is **online** and that it is assigned to the correct queue.
 
 Confirm that the agent is online and connected to the queue `buildkite-queue1`.
 
 ![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. 
+Congratulations! Your Buildkite agent is now set up and connected to your queue. You can now start using Buildkite to build multi-architecture images on your Arm-based VM. This setup enables you to run CI/CD pipelines optimized for Arm platforms, and take advantage of the performance and scalability of Arm servers.

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

@@ -105,4 +105,6 @@ Trigger a new build by clicking New Build on your pipeline’s dashboard.
 
 ![Buildkite Dashboard alt-text#center](images/build-p.png "Create Build")
 
-Once your files and pipeline are ready, you can validate that your Buildkite agent is running and ready to execute jobs.
+## What you've accomplished
+
+You've now created a simple Flask application, added a Dockerfile, set up your GitHub repository, and configured a Buildkite pipeline for multi-architecture builds on Arm. You also added Docker credentials as secrets and defined your pipeline steps in YAML. These steps prepare you to build, push, and test containerized applications using Arm-based infrastructure. You're now ready to validate your setup and run your first build!

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

@@ -12,7 +12,7 @@ Follow the steps below to run your pipeline on an Arm-based Buildkite agent. You
 
 ## 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:
+Before running your pipeline, make sure the Buildkite agent is active and connected. On your VM, check the agent status with this command:
 
 ```console
 sudo /root/.buildkite-agent/bin/buildkite-agent status
@@ -24,26 +24,26 @@ This command checks the current state of your Buildkite agent and displays its c
 
 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")
+![Screenshot of the Buildkite dashboard showing the "New Build" button highlighted, with the pipeline name and branch selection visible. This interface allows you to trigger a new build and select the branch to build from.](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
+You can watch your build logs in real time in the Buildkite dashboard. Each step appears as it runs, so you can track progress and spot any issues quickly.
 
-You can see the logs of your build live in the Buildkite UI.
+The main steps you'll see are:
 
-The steps include:
-- Docker login
-- Buildx builder creation
-- Multi-arch Docker image build and push
+- Logging in to Docker
+- Creating the Buildx builder
+- Building and pushing the multi-architecture Docker image
 
-![Buildkite Dashboard alt-text#center](images/log.png "Monitor the build")
+![Screenshot of the Buildkite dashboard displaying real-time build logs, showing each pipeline step and its status for monitoring progress](images/log.png "Monitor the build")
 
 ## 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")
+![Screenshot of Docker Hub showing the multi-architecture image for the application repository, confirming both arm64 and amd64 platforms are available](images/multi-arch-image.png "Docker image")
 
 ## Run the Flask application
 
@@ -54,18 +54,14 @@ docker run --rm -p 80:5000 <DOCKER_USERNAME>/multi-arch-app:latest
 
 This command runs the Flask application inside a container, exposing it on port 5000 inside the container and mapping it to port 80 on the host machine.
 
-You can now visit the VM’s Public IP to access the Flask application.
+You can now visit the VM’s Public IP to access the Flask application:
 
 ```console
 http://<VM_IP>
 ```
 You should see output similar to:
+![Screenshot of the Docker Hub web interface showing the multi-architecture image tags for the application repository, confirming successful upload of both arm64 and amd64 images](images/browser.png "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
+## What you've accomplished
 
 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!