second pass

Author: anupras-mohapatra-arm

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/2-environment-setup.md

@@ -14,9 +14,11 @@ Start with the [Azure Cobalt Learning Path](https://learn.arm.com/learning-paths
 
 This path was validated with Ubuntu 24.04 LTS on Azure Cobalt in `westus2` (example VM size: `Standard_D2ps_v6`, 2 vCPUs).
 
-### Install tools on Cobalt VM
+### Install tools on the Azure virtual machine
 
-Install the toolchain on the Cobalt VM before building and testing. The commands install the Linux packages used throughout this Learning Path: source control, HTTP validation, JSON inspection, Python for the endpoint tester, package archive inspection, Docker, and the .NET 9 SDK from the Ubuntu backports feed.
+Install the toolchain on the Azure VM before building and testing. 
+
+The following commands install the Linux packages used throughout this Learning Path: source control, HTTP validation, JSON inspection, Python for the endpoint tester, package archive inspection, Docker, and the .NET 9 SDK from the Ubuntu backports feed:
 
 ```bash
 sudo apt-get update -y
@@ -46,13 +48,15 @@ aarch64
 Docker version ...
 ```
 
-If you're upgrading from an older .NET version before migrating to Cobalt, use [GitHub Copilot modernization for .NET](https://learn.microsoft.com/dotnet/core/porting/github-copilot-app-modernization/overview) to assess the project and guide the upgrade. In Visual Studio Code, open Copilot Chat and use `@modernize-dotnet`; in Visual Studio, use the Modernize action from Solution Explorer.
+If you're upgrading from an older .NET version before migrating to Cobalt, use [GitHub Copilot modernization for .NET](https://learn.microsoft.com/dotnet/core/porting/github-copilot-app-modernization/overview) to assess the project and guide the upgrade. In Visual Studio Code, open Copilot Chat and use `@modernize-dotnet`. In Visual Studio, use the **Modernize** action from **Solution Explorer**.
+
+### Enable citext to satisfy PostgreSQL prerequisite 
 
-#### Enable citext to satisfy PostgreSQL prerequisite 
+nopCommerce defaults to SQL Server, but you'll use PostgreSQL for Arm validation. For PostgreSQL installs, you need `citext` before migration and installation. Without it, installer migrations fail with `type "citext" does not exist` (captured in local test artifacts).
 
-nopCommerce defaults to SQL Server, but you'll use PostgreSQL for Arm validation. For PostgreSQL installs, you need `citext` before migration or installation. Without it, installer migrations fail with `type "citext" does not exist` (captured in local test artifacts).
+Create PostgreSQL and enable `citext` before running the installer. The database runs in Docker on the Cobalt VM so the nopCommerce app can connect to `127.0.0.1:5432` during the local validation phase. 
 
-Create PostgreSQL and enable `citext` before running the installer. The database runs in Docker on the Cobalt VM so the nopCommerce app can connect to `127.0.0.1:5432` during the local validation phase. Replace the password value before running the command.
+Replace the password value before running the following commands:
 
 ```bash
 export NOP_POSTGRES_PASSWORD='replace-with-a-strong-password'

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/3-checkout-build-baseline.md

@@ -8,11 +8,15 @@ layout: learningpathall
 
 ## Build and baseline
 
-Create a reproducible Arm baseline before optimization work. This page pins source, verifies a clean build, and captures a representative endpoint baseline so later changes can be measured against a known control.
+Create a reproducible Arm baseline before optimization work. 
+
+You'll pin the source, verify a clean build, and capture a representative endpoint baseline so you can measure later changes against a known control.
 
 ### Clone and pin the source
 
-Pinning the exact tag and commit avoids silent drift in dependencies and behavior. Run the following commands on the Cobalt virtual machine (VM):
+Pinning the exact tag and commit avoids silent drift in dependencies and behavior. 
+
+Run the following commands on the Arm-based virtual machine (VM):
 
 ```bash
 git clone https://github.com/nopSolutions/nopCommerce.git
@@ -31,7 +35,7 @@ cd ~/nopCommerce  # replace with your clone path if different
 
 ### Restore and build on Arm
 
-Run restore and build on the Arm-based VM to establish a native Arm baseline. Restoring first separates package resolution problems from compilation problems, and `--no-restore` makes the build validate the already restored dependency graph.
+Run restore and build on the Arm-based VM to establish a native Arm baseline:
 
 ```bash
 # Restore dependencies first so build failures are easier to triage.
@@ -40,15 +44,17 @@ dotnet restore src/Presentation/Nop.Web/Nop.Web.csproj
 # Build release binaries without re-restoring packages.
 dotnet build src/Presentation/Nop.Web/Nop.Web.csproj -c Release --no-restore
 ```
+Restoring first separates package resolution problems from compilation problems, and `--no-restore` makes the build validate the already restored dependency graph.
 
 ### Start and install nopCommerce
 
-Start the app locally and complete installer setup with PostgreSQL. Run this command in one terminal and leave it running; `dotnet run` hosts the web application and keeps the terminal attached to the server logs.
+Start the app locally and complete installer setup with PostgreSQL. Run the following command in one terminal and leave it running: 
 
 ```bash
 cd src/Presentation/Nop.Web
 dotnet run -c Release --no-build --urls http://0.0.0.0:5000
 ```
+`dotnet run` hosts the web application and keeps the terminal attached to the server logs.
 
 In a browser, open `http://<cobalt-public-ip>:5000` or use an SSH tunnel to reach `http://127.0.0.1:5000`. On the nopCommerce install page, select PostgreSQL and use the database settings from the previous section:
 
@@ -72,7 +78,7 @@ curl -s -o /dev/null -w 'root=%{http_code}\n' http://127.0.0.1:5000/
 curl -s -o /dev/null -w 'install=%{http_code}\n' http://127.0.0.1:5000/install
 ```
 
-Expected after successful install: `root=200`, `install=302`.
+The outputs after a successful install should be: `root=200`, `install=302`.
 
 ### Run the baseline
 
@@ -85,7 +91,7 @@ Don't benchmark `/install`. Baseline stable storefront paths first, then add car
 - Product and category pages from your sample data
 - Cart or checkout endpoints from a recorded production-like workflow
 
-Create the endpoint tester in the repository root. The script uses only the Python standard library, submits requests with fixed concurrency, treats non-2xx and non-3xx responses as errors, and writes raw samples plus per-route summaries to JSON.
+Create the endpoint tester in the repository root:
 
 ```python {file_name="test_nopcommerce_endpoints.py"}
 #!/usr/bin/env python3
@@ -199,6 +205,8 @@ if __name__ == "__main__":
     main()
 ```
 
+The script uses only the Python standard library, submits requests with fixed concurrency, treats non-2xx and non-3xx responses as errors, and writes raw samples plus per-route summaries to JSON.
+
 Run the endpoint tester from the repository root while the app is still running in the first terminal:
 
 ```bash
@@ -210,14 +218,14 @@ python3 test_nopcommerce_endpoints.py \
   --json-out arm_before.json
 ```
 
-The command prints the per-route summary and writes the raw measurements to `arm_before.json`. Keep that JSON file unchanged; it is the baseline artifact used by the tuning step.
+The command prints the per-route summary and writes the raw measurements to `arm_before.json`. Keep that JSON file unchanged because it's the baseline artifact used in the tuning step.
 
 #### Baseline quality rules
 
 Use these rules before you compare any optimization result:
 
-- Run at least 3 baseline trials with identical parameters.
-- Keep endpoint order fixed per run (not randomized) when comparing before vs after.
+- Run at least three baseline trials with identical parameters.
+- Keep endpoint order fixed per run (not randomized) when comparing before and after.
 - Keep database state and seeded data identical across runs.
 - Capture raw JSON for every run and compare medians, not single outliers.
 

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/4-dependency-mapping-manifests.md

@@ -6,7 +6,7 @@ weight: 4
 layout: learningpathall
 ---
 
-## Audit application ependencies
+## Audit application dependencies
 
 Run dependency discovery before migration changes so you understand direct references, transitive risk, and hidden native payloads. By doing so, you'll avoid late surprises when deploying to Arm.
 

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/6-deploy-verify-cobalt.md

@@ -82,16 +82,13 @@ Use these rules before adopting a tuning profile:
 - Reset warm-up policy consistently (always warm or always cold).
 - Require improvement in both throughput and p95 latency, not just one.
 - Set a minimum practical threshold (for example, >=5% median gain) before rollout.
-
-#### Instance-size tradeoffs
-
-Do not assume the same profile wins on every Azure Cobalt VM size. Smaller instances often benefit from lower CPU burn and predictable p95 latency. Larger instances often benefit from higher concurrency, but can expose GC, database, and shared-resource contention. Compare throughput, p95/p99 latency, CPU utilization, and error rate for each instance size before keeping a tuning profile.
+- Don't assume the same profile wins on every Azure VM size. Smaller instances often benefit from lower CPU burn and predictable p95 latency. Larger instances often benefit from higher concurrency, but can expose GC, database, and shared-resource contention. Compare throughput, p95/p99 latency, CPU utilization, and error rate for each instance size before keeping a tuning profile.
 
 ### Considerations for interpreting metric improvements
 
 When interpeting metric improvements, consider the following:
 
-- If only one metric improves while p95 or error rate regresses, do not treat the change as a win.
+- If only one metric improves while p95 or error rate regresses, don't treat the change as a win.
 - If run-to-run variation is near the observed delta, treat it as noise.
 - Keep architecture-specific profiles separate. Don't force one profile onto all architectures.