Wording tweaks

Author: chriswblake

.github/steps/1-step.md

@@ -1,27 +1,27 @@
-## Step 1: Enable CodeQL
+## Step 1: Enable Code Scanning
 
-In this first step, we'll be learning more about [CodeQL](https://codeql.github.com/) and how to use it to secure your source code.
+Let's start by learning a bit about code scanning with [CodeQL](https://codeql.github.com/) and how it helps secure your code.
 
 ### What is GitHub Code Scanning?
 
-[Code scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning) is part of the [GitHub Advanced Security (GHAS)](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) product suite. It allows development teams to integrate security testing tools directly into the same process you already use for shipping code. It supports many types such as SAST, container, and infrastructure as code. And the best part is that the results can also live directly in GitHub next to your code. No need for context switching! 🎉
+[Code scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning) is part of the [GitHub Advanced Security (GHAS)](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) product suite. It allows development teams to integrate security testing tools directly into the same process you already use for shipping code. It supports many types such as SAST, container, and infrastructure as code. And, the best part is that the results can also live directly in GitHub next to your code. No need for context switching! 🎉
 
 > [!TIP]
-> All of the features of GitHub Advanced Security are 100% free for public repositories.
+> All features of GitHub Advanced Security are free for public repositories. However, private repositories require a compatible [paid account](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security).
 
 ### What is CodeQL?
 
 [CodeQL](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql) is a static analysis testing tool that helps you identify security weaknesses such as SQL injection, cross-site scripting, and code injection issues.
 
-Typically CodeQL patterns are collected into [query suites](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql#about-codeql-queries) of patterns. When combined well, this can be a very powerful! To help with this, teams of security experts have pre-populated suites for many common scenarios and programming languages.
+Typically CodeQL [queries](https://codeql.github.com/docs/writing-codeql-queries/about-codeql-queries/) are collected into [query suites](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql#about-codeql-queries) to cover multiple patterns. When combined well, this can be a very powerful! To help with this, teams of security experts have pre-populated suites for many common scenarios and programming languages.
 
 In many cases, taking advantage of CodeQL is as simple as accepting the default suite, but you can also select the extended suite or customize your own with [GitHub Actions]().
 
 <img width="200" align="right" alt="codeql default configuration box" src="https://github.com/user-attachments/assets/cf5ba96b-98bb-4db5-b743-bd31bceaabac"/>
 
-Here are some options the default configuration provides:
+Here are some of the options the default configuration provides:
 
-- **Languages:** The languages automatically detected in your repository that CodeQL will scan.
+- **Languages:** Supported languages will automatically detected in your repository and scanning will be enabled.
 
 - **Query suites:** A list of the available suites of patterns that will be used. The **Default** or **Extended** are provided automatically.
 

.github/steps/2-step.md

@@ -1,6 +1,6 @@
 ## Step 2: Detect Vulnerabilities in a Pull Request
 
-In this step, we will introduce a vulnerability into the `routes.py` file to trigger an alert.
+To see how Code Scanning works, we will introduce a vulnerability into the `routes.py` file to trigger an alert.
 
 ### ⌨️ Activity: Create a vulnerability
 
@@ -10,17 +10,17 @@ In this step, we will introduce a vulnerability into the `routes.py` file to tri
 
 1. In the top right of the preview, click the **Edit** button.
 
-   <img width="400" alt="edit button" src="https://github.com/user-attachments/assets/19462cc5-a360-4dae-a97b-ecfd571aa403"/>
+   <img width="500" alt="edit button" src="https://github.com/user-attachments/assets/19462cc5-a360-4dae-a97b-ecfd571aa403"/>
 
 1. Navigate to about **line 16** and modify it to the below.
 
    ```py
    "SELECT * FROM books WHERE name LIKE '%" + name + "%'"
    ```
 
-1. Above the editor in the top-right, click the **Commit changes...** button. Select the radio button next to **Create a new branch** option. **DO NOT commit to the main branch.**
+1. Above the editor in the top-right, click the **Commit changes...** button. In the prompt window, select the radio button for the **Create a new branch** option. **DO NOT commit to the main branch.**
 
-1. Click the **Propose changes** option and click **Create pull request**. Use the following branch name.
+1. Click the **Propose changes** option and click **Create pull request**. Use the below branch name.
 
    ```txt
    learning-codeql
@@ -58,5 +58,4 @@ In this step, we will introduce a vulnerability into the `routes.py` file to tri
 > [!TIP]
 > Check out the [Triage code scanning alerts in pull requests](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/triaging-code-scanning-alerts-in-pull-requests) page to learn more about integration of code scanning into pull requests.
 
-
-<!-- > 💡 Tip: Clicking the **Show paths** link will provide additional insights about the alert's data flow from user input (source), through the application, and when it is acted on (sink). -->
+<!-- > 💡 Tip: Clicking the **Show paths** link will provide additional insights about the alert's data flow from user input (source), through the application, and when it is acted on (sink). -->

.github/steps/3-step.md

@@ -1,6 +1,6 @@
 ## Step 3: Review and Triage CodeQL Alerts
 
-With our pull request changes now reviewed by CodeQL, let's take a moment to learn about managing alerts.
+With our pull request changes now reviewed by CodeQL, we now have some results to view.Let's learn about managing alerts.
 
 GitHub provides a dedicated **Security** tab for securely managing all security related issues. CodeQL saves alerts using the same standard as many other analysis tools with the results showing up under the **Code scanning** area.
 
@@ -10,13 +10,15 @@ GitHub provides a dedicated **Security** tab for securely managing all security
 
 The main area of an alert provides the resolution status, affected branch, code location, and classification information like severity and [CVE identification number](https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories#cve-identification-numbers).
 
+After the status information, a detailed description of the issue, recommended solutions, and suggested code changes are provided.
+
 <img width="600" alt="additional information" src="https://github.com/user-attachments/assets/9a5aaf3f-e063-4d07-8cdd-6272eec8a411"/>
 
 ### What is CWE?
 
-Many of the patterns CodeQL scans for come from existing databases of vulnerabilities.
+Many of the patterns CodeQL scans for come from existing databases of vulnerabilities, which are categorized for easier understanding.
 
-The Common Weakness Enumeration (CWE) is a category system for hardware and software weaknesses and vulnerabilities. Think of it as a way to describe and categorize security issues in an application's source code. For more information on CWEs, see the Wikipedia article [Common Weakness Enumeration](https://en.wikipedia.org/wiki/Common_Weakness_Enumeration).
+The **Common Weakness Enumeration (CWE)** is a category system for hardware and software weaknesses and vulnerabilities. Think of it as a way to describe and categorize security issues in an application's source code. For more information on CWEs, see the Wikipedia article [Common Weakness Enumeration](https://en.wikipedia.org/wiki/Common_Weakness_Enumeration).
 
 ### ⌨️ Activity: Review an Alert
 

.github/steps/4-step.md

@@ -1,6 +1,6 @@
 ## Step 4: Fix Security Vulnerabilities
 
-Let's fix the security vulnerability we introduced that CodeQL identified.
+Finally, let's use the information provided by CodeQL to better understand the vulnerability and fix it.
 
 ### ⌨️ Activity: Resolve an open alert