Update how-to-1.md

Author: madeline-underwood

content/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/how-to-1.md

@@ -6,24 +6,24 @@ weight: 2
 layout: learningpathall
 ---
 
-## Overview
+## What are flame graphs?
 
-A flame graph is a visualization built from many sampled call stacks that shows where a program spends CPU time. In a performance investigation it is often the first thing to generate when it is not yet clear which parts of the codebase are affecting execution time. Instead of guessing where the bottleneck is, you take a quick sample of real execution and use the resulting graph to identify the hottest code paths that deserve deeper analysis.
+A flame graph is a visualization built from many sampled call stacks that shows where a program spends CPU time. In a performance investigation it's often the first thing to generate when it isn't yet clear which parts of the codebase are affecting execution time. Instead of guessing where the bottleneck is, you take a quick sample of real execution and use the resulting graph to identify the hottest code paths that deserve deeper analysis.
 
-## Example Flame Graph
+## How to read a flame graph
 
 The flame graph below shows a typical profiling result.
 
-![A flame graph showing function call stacks. The x-axis shows relative sample frequency and the y-axis shows call stack depth, with the widest blocks representing functions that consumed the most CPU time#center](./flame-graph-example.jpg "Example flame graph")
+![A flame graph showing function call stacks with the x-axis representing relative sample frequency and the y-axis showing call stack depth. Wider blocks indicate functions that consumed more CPU time during profiling.#center](./flame-graph-example.jpg "Example flame graph")
 
 The x-axis represents the relative number of samples attributed to code paths, ordered alphabetically, not a timeline. A wider block means that function appeared in more samples and therefore consumed more CPU time. The y-axis represents call stack depth. Frames at the bottom are closer to the root of execution, such as a thread entry point, and frames above them are functions called by those below.
 
 Each sample captures a snapshot of the current call stack. Many samples are then aggregated by grouping identical stacks and summing their counts, which is what makes flame graphs compact and readable. A common workflow is to start with the widest blocks, then move upward through the stack to understand which callees dominate that hot path. Reliable stack walking depends on frame pointers being present; they allow the profiler to unwind through nested calls and produce accurate stacks that merge cleanly into stable blocks.
 
-This Learning Path does not cover flame graphs in depth. To learn more, see [Brendan Gregg's flame graph reference](https://www.brendangregg.com/flamegraphs.html).
+This Learning Path doesn't cover flame graphs in depth. To learn more, see [Brendan Gregg's flame graph reference](https://www.brendangregg.com/flamegraphs.html).
 
 ## Tooling options
 
-On Linux, flame graphs are commonly generated from samples collected with `perf`. perf periodically interrupts the running program and records a stack trace, then the collected stacks are converted into a folded format and rendered as the graph. Sampling frequency is important. If the frequency is too low you may miss short-lived hotspots, and if it is too high you may introduce overhead or skew the results. To make the output informative, compile with debug symbols and preserve frame pointers so stacks resolve to meaningful function names and unwind reliably. A typical build uses `-g` and `-fno-omit-frame-pointer`.
+On Linux, flame graphs are commonly generated from samples collected with `perf`. perf periodically interrupts the running program and records a stack trace, then the collected stacks are converted into a folded format and rendered as the graph. Sampling frequency is important. If the frequency is too low you might miss short-lived hotspots, and if it's too high you might introduce overhead or skew the results. To make the output informative, compile with debug symbols and preserve frame pointers so stacks resolve to meaningful function names and unwind reliably. A typical build uses `-g` and `-fno-omit-frame-pointer`.
 
-Arm has built a tool, Arm Performix that simplifies this workflow through the Code Hotspots recipe, making it easier to configure collection, run captures, and explore the resulting call hierarchies without manually stitching together the individual steps. This is the tooling solution you will use in this Learning Path.
+Arm has built a tool, Arm Performix that simplifies this workflow through the Code Hotspots recipe, making it easier to configure collection, run captures, and explore the resulting call hierarchies without manually stitching together the individual steps. This is the tooling solution you'll use in this Learning Path.

content/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/how-to-2.md

@@ -13,11 +13,11 @@ This Learning Path uses a hands-on worked example to make sampling-based profili
 A fractal is a pattern that shows detail at many scales, often with self-similar structure. Fractals are usually generated by repeatedly applying a simple mathematical rule. In the Mandelbrot set, each pixel corresponds to a complex number, which is iterated through a basic recurrence. How quickly the value “escapes” (or whether it stays bounded) determines the pixel’s color and produces the familiar Mandelbrot image.
 
 You don't need to understand the Mandelbrot algorithm in detail to follow this Learning Path — it's used here as a convenient, compute-heavy workload for profiling. To learn more, see the [Mandelbrot set article on Wikipedia](https://en.wikipedia.org/wiki/Mandelbrot_set).
- 
+
 
 ## Connect to Target
 
-See the [Arm Performix installation guide](https://learn.arm.com/install-guides/atp) if this is your first time setting up Arm Performix. In this Learning Path you will connect to an AWS Graviton3 metal instance (`m7g.metal`) with 64 Neoverse V1 cores, your remote target server. From the host machine, test the connection to the remote server by navigating to **Targets** > **Test Connection**. You should see the successful connection screen below.
+If this is your first time setting up Arm Performix, follow the [Arm Performix installation guide](/install-guides/atp/). In this Learning Path you'll connect to an AWS Graviton3 metal instance (`m7g.metal`) with 64 Neoverse V1 cores, your remote target server. From the host machine, test the connection to the remote server by navigating to **Targets** > **Test Connection**. You should see the successful connection screen below.
 
 ![The Arm Performix Targets panel showing a successful connection test result for a remote Arm server#center](./successful-connection.jpg "Successful connection to remote target")
 

content/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/how-to-3.md

@@ -40,9 +40,9 @@ make clean
 make single_thread DEBUG=1
  ```
 
-Open APX from the host machine. Select the **Code Hotspot** recipe. If this is the first time running the recipe on this target machine you may need to select the install tools button.
+Open APX from the host machine. Select the **Code Hotspot** recipe. If this is the first time running the recipe on this target machine you might need to select the install tools button.
 
-![The Arm Performix recipe selection screen with the Code Hotspots recipe highlighted#center](./install-tools.jpg "Selecting the Code Hotspots recipe")
+![The Arm Performix recipe selection screen with the Code Hotspots recipe highlighted and the install tools button visible for first-time setup#center](./install-tools.jpg "Selecting the Code Hotspots recipe")
 
 Configure the recipe to launch a new process. APX will automatically start collecting metrics when the program starts and stop when the program exits.
 
@@ -62,7 +62,7 @@ To investigate further, you can map source code lines to the functions in the fl
 
 ![The Arm Performix flame graph view showing source code annotations mapped to the selected hot function#center](./view-with-source-code.jpg "Flame graph with source code view")
 
-Finally, check your `images` directory for the generated bitmap fractal `green.bmp`
+Finally, check your `images` directory for the generated bitmap fractal `green.bmp`. This confirms the application ran successfully and produced the expected Mandelbrot set visualization.
 
-![A rendered Mandelbrot set fractal in green, generated from the single-threaded build at maximum iterations#center](./plot-1-thread-max-iterations.jpg "Mandelbrot fractal output from single-threaded build")
+![A rendered Mandelbrot set fractal in green showing the characteristic self-similar structure at maximum iterations. This is the baseline output you'll use for performance comparison.#center](./plot-1-thread-max-iterations.jpg "Mandelbrot fractal output from single-threaded build")
 

content/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/how-to-4.md

@@ -44,7 +44,7 @@ Select the refresh icon in the top right to rerun the recipe, then switch to com
 
 There is negligible difference in perceived image quality when halving `MAX_ITERATIONS`.
 
-![Side-by-side comparison of Mandelbrot fractal output at MAX_ITERATIONS 1024 and 512, showing no visible quality difference#center](./comparison.jpg "Image quality comparison: 1024 vs 512 iterations")
+![Side-by-side comparison of Mandelbrot fractal output at MAX_ITERATIONS 1024 (left) and 512 (right). Both images show the same level of detail and structure, confirming that the reduced iteration count doesn't compromise visual quality.#center](./comparison.jpg "Image quality comparison: 1024 vs 512 iterations")
 
 ### Optimization 2 - Parallelising the hot function
 
@@ -82,7 +82,7 @@ The total run duration shown in APX includes tooling setup and data analysis tim
 
 ### (Optional Challenge) Additional optimizations
 
-The `Makefile` uses the `-O0` flag when the `DEBUG=1` argument is passed in. This disables all compiler optimizations. Try experimenting with higher optimization levels, different loop boundary sizes, and thread counts. See the Learning Path [Get started with compiler optimization flags](/learning-paths/servers-and-cloud-computing/cplusplus_compilers_flags/) for guidance. You may also want to explore vectorized math libraries that could replace the `libm` hypotenuse function, such as the [Arm Performance Libraries vector math functions](https://developer.arm.com/documentation/101004/2601/Arm-Performance-Libraries-Math-Functions/Arm-Performance-Libraries-Vector-Math-Functions--Accuracy-Table).
+The `Makefile` uses the `-O0` flag when the `DEBUG=1` argument is passed in. This disables all compiler optimizations. Try experimenting with higher optimization levels, different loop boundary sizes, and thread counts. See the Learning Path [Get started with compiler optimization flags](/learning-paths/servers-and-cloud-computing/cplusplus_compilers_flags/) for guidance. You might also want to explore vectorized math libraries that could replace the `libm` hypotenuse function, such as the [Arm Performance Libraries vector math functions](https://developer.arm.com/documentation/101004/2601/Arm-Performance-Libraries-Math-Functions/Arm-Performance-Libraries-Vector-Math-Functions--Accuracy-Table).
 
 
 ## Summary