Refine documentation for Buildkite pipeline setup: improve clarity, section titles, and image descriptions.

Author: madeline-underwood

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

@@ -8,11 +8,11 @@ layout: learningpathall
 
 ## Create an application
 
-You can now create an application to containerize with Docker. The example below is a simple Flask-based Python application.
+Now you'll create a simple application to containerize with Docker. This example uses Flask, a popular Python web framework.
 
-Create a new public GitHub repository where you can create the Dockerfile and the Python file for the application.
+The first step is to create a new public GitHub repository. You'll add both the `Dockerfile` and the Python application file to this repository.
 
-### Create a Dockerfile
+## Create a Dockerfile
 
 In a GitHub repo, add a new file named `Dockerfile` with this content:
 
@@ -30,7 +30,7 @@ EXPOSE 5000
 CMD ["python", "app.py"]
 ```
 
-### Create a Python application
+## Create a Python application
 
 In the same repo, add a Python source file named `app.py`:
 
@@ -48,37 +48,34 @@ if __name__ == "__main__":
 
 This Python code defines a simple Flask web server that listens on all interfaces (0.0.0.0) at port 5000 and responds with "Hello from Arm-based Buildkite runner!" when the root URL (/) is accessed.
 
-### Add the code to your GitHub repository
+## Add your code to the GitHub repository
 
-Before triggering the pipeline, your GitHub repository should have:
+Before you trigger the Buildkite pipeline, make sure your GitHub repository contains both the `Dockerfile` and the `app.py` file. The `Dockerfile` defines your multi-architecture container image, and `app.py` is your Python microservice.
 
-- `Dockerfile` (defines your multi-arch image)
-- `app.py` (your Python microservice)
+You'll need the URL of this repository when you create your Buildkite pipeline in the next steps.
 
-You will need the path to the GitHub repository when you create a Buildkite pipeline below.
-
-### Add Docker credentials as Buildkite secrets
+## Add Docker credentials as Buildkite secrets
 
 Make sure to add your Docker credentials as secrets in the Buildkite UI.
 
 Navigate to Buildkite and select Agents and then Secrets and add `DOCKER_USERNAME` and `DOCKER_PASSWORD`.
 
 ![Buildkite Dashboard alt-text#center](images/secrets.png "Set Secrets")
 
-### Create a Buildkite pipeline for multi-arch builds
+## Create a Buildkite pipeline for multi-arch builds
 
 In Buildkite, define your pipeline using YAML through the UI.
 
 Go to the Buildkite Dashboard and select Pipelines and New Pipeline
 
-Fill out the form:
+Fill out the form using the following details:
 
    - Git Repository: Enter your GitHub repository URL (SSH or HTTPS).  
    - Name: Enter a name for your pipeline.
 
 ![Buildkite Dashboard alt-text#center](images/pipeline.png "Create Pipeline")
 
-In the Steps (YAML Steps) section, paste your pipeline YAML.
+In the Steps (YAML Steps) section, paste your pipeline YAML:
 
 ```yaml
 steps:
@@ -99,9 +96,9 @@ steps:
 
 ![Buildkite Dashboard alt-text#center](images/yaml.png "YAML steps")
 
-Click Create Pipeline.
+Select **Create pipeline** to save your new pipeline.
 
-Trigger a new build by clicking New Build on your pipeline’s dashboard.
+To start your first build, select **New build** on your pipeline dashboard. This action triggers the pipeline and begins the multi-architecture build process.
 
 ![Buildkite Dashboard alt-text#center](images/build-p.png "Create Build")
 

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

@@ -24,11 +24,11 @@ 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.
 
-![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")
+![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 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 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.
 
 The main steps you'll see are:
@@ -37,13 +37,13 @@ The main steps you'll see are:
 - Creating the Buildx builder
 - Building and pushing the multi-architecture Docker image
 
-![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")
+![Screenshot of the Buildkite dashboard displaying real-time build logs, showing each pipeline step and its status for monitoring progress alt-text#center](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:
 
-![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")
+![Screenshot of Docker Hub showing the multi-architecture image for the application repository, confirming both arm64 and amd64 platforms are available alt-text#center](images/multi-arch-image.png "Docker image")
 
 ## Run the Flask application
 
@@ -60,7 +60,7 @@ You can now visit the VM’s Public IP to access the Flask application:
 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")
+![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 alt-text#center](images/browser.png "Verify Docker images")
 
 ## What you've accomplished