Improve formatting and clarity in Kafka documentation

Author: madeline-underwood

content/learning-paths/servers-and-cloud-computing/kafka-azure/baseline.md

@@ -27,14 +27,14 @@ KRaft (Kafka Raft) mode replaces ZooKeeper by managing metadata directly within
 Before you start Kafka in KRaft mode, you need to configure the broker and initialize the storage directory. You only need to do this once for each broker.
 
 
-- **Edit the configuration file**  
+ ## Edit the configuration file
     Open the Kafka configuration file in an editor:
 
     ```console
     vi /opt/kafka/config/server.properties
     ```
 
-- **Add or modify KRaft properties**  
+## Add or modify KRaft properties
     Ensure the following configuration entries are present for a single-node KRaft setup:
 
     ```java
@@ -47,7 +47,7 @@ Before you start Kafka in KRaft mode, you need to configure the broker and initi
     ```
     This configuration file sets up a single Kafka server to act as both a controller (managing cluster metadata) and a broker (handling data), running in KRaft mode. It defines the node's unique ID and specifies the local host as the sole participant in the controller quorum.
 
-- **Format the storage directory**  
+## Format the storage directory
     Format the metadata storage directory using the kafka-storage.sh tool. This initializes KRaft’s internal Raft logs with a unique cluster ID.
 
     ```console
@@ -60,7 +60,7 @@ Before you start Kafka in KRaft mode, you need to configure the broker and initi
     ```
     This confirms that the Kafka storage directory has been successfully formatted and that the broker is ready to start in KRaft mode.
 
-## Perform the Baseline Test
+## Perform the baseline test
 With Kafka 4.1.0 installed and configured in KRaft mode, you’re now ready to run a baseline test to verify that the Kafka broker starts correctly, topics can be created, and message flow works as expected.
 
 You’ll use multiple terminals for this test:
@@ -78,7 +78,7 @@ bin/kafka-server-start.sh config/server.properties
 ```
 Keep this terminal open and running. The broker process must stay active for all subsequent commands.
 
-## Terminal 2 - create a Topic
+## Terminal 2 - create a topic
 Open a new terminal window. Create a topic named test-topic-kafka, which acts as a logical channel where producers send and consumers receive messages:
 
 ```console

content/learning-paths/servers-and-cloud-computing/kafka-azure/benchmarking.md

@@ -107,9 +107,6 @@ The producer sustained a throughput of ~257,500 records/sec (~24.5 MB/sec) with
 The 95th percentile latency (1168 ms) and 99th percentile (1220 ms) show predictable network and I/O performance.
 Kafka maintained consistent throughput, even under full-speed production, with no message loss or broker errors reported.
 
-### Benchmark Comparison Insights
-When analyzing performance on Azure Cobalt 100 Arm64 virtual machines:
-   **Producer efficiency**: The producer reached ~23–25 MB/sec throughput with average latencies below 900 ms, demonstrating stable delivery rates for high-volume workloads.
-   **Consumer scalability**: The consumer maintained ~262K messages/sec throughput with near-linear scaling of fetch performance — exceeding 1.85M messages/sec internally.
-   **Performance stability**: Both producer and consumer benchmarks showed low jitter and consistent latency distribution across iterations, confirming Kafka’s predictable behavior on Arm-based VMs.
+### Benchmark comparison insights
+When analyzing performance on Azure Cobalt 100 Arm64 virtual machines, you’ll notice that Kafka delivers stable and predictable results for both producers and consumers. The producer consistently achieves throughput between 23 MB/sec and 25 MB/sec, with average latencies below 900 ms. This means you can rely on efficient message delivery, even when handling high-volume workloads. On the consumer side, throughput remains strong at around 262,000 messages per second, and fetch performance scales nearly linearly, often exceeding 1.85 million messages per second internally. Throughout multiple benchmark runs, both producer and consumer tests demonstrate low jitter and consistent latency distribution, confirming that Kafka maintains reliable performance on Arm-based virtual machines.
 

content/learning-paths/servers-and-cloud-computing/kafka-azure/create-instance.md

@@ -14,7 +14,7 @@ These VMs are designed for a wide range of workloads and offer Arm-based perform
 
 If you have never used the Microsoft Cloud Platform before, see the Microsoft guide on how to [Create a Linux virtual machine in the Azure portal](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/quick-create-portal?tabs=ubuntu). 
 
-## Create an Arm-based Azure Virtual Machine 
+## Create an Arm-based Azure virtual machine 
 
 Creating a virtual machine based on Azure Cobalt 100 is no different from creating any other virtual machine in Azure. To create an Azure virtual machine, launch the Azure portal and navigate to **Virtual Machines**.
 
@@ -23,29 +23,29 @@ Creating a virtual machine based on Azure Cobalt 100 is no different from creati
 - Choose the image for your virtual machine (for example, Ubuntu Pro 24.04 LTS) and select **Arm64** as the VM architecture.
 - In the **Size** field, click on **See all sizes** and select the D-Series v6 family of virtual machines. Select **D4ps_v6** from the list.
 
-![Azure portal showing the selection of the D-Series v6 family of virtual machines, with D4ps_v6 highlighted as the chosen size. The interface displays a list of available VM sizes, including CPU, memory, and pricing details. The wider environment is the Azure portal's virtual machine creation workflow, with a clean and organized layout. The tone is neutral and informative, focused on guiding users through the selection process. Visible text includes D-Series v6, D4ps_v6, CPU, memory, and price columns.](images/instance.png "Selecting the D-Series v6 family of virtual machines")
+![Azure portal showing the selection of the D-Series v6 family of virtual machines, with D4ps_v6 highlighted as the chosen size. The interface displays a list of available VM sizes, including CPU, memory, and pricing details. The wider environment is the Azure portal's virtual machine creation workflow, with a clean and organized layout. The tone is neutral and informative, focused on guiding users through the selection process. Visible text includes D-Series v6, D4ps_v6, CPU, memory, and price columns. alt-text#center](images/instance.png "Selecting the D-Series v6 family of virtual machines")
 
-5. Select "SSH public key" as an Authentication type. Azure will automatically generate an SSH key pair for you and allow you to store it for future use. It is a fast, simple, and secure way to connect to your virtual machine.
-6. Fill in the Administrator username for your VM.
-7. Select "Generate new key pair", and select "RSA SSH Format" as the SSH Key Type. RSA could offer better security with keys longer than 3072 bits. Give a Key pair name to your SSH key.
-8. In the "Inbound port rules", select HTTP (80) and SSH (22) as the inbound ports.
+- Select **SSH public key** as an authentication type. Azure automatically generates an SSH key pair for you and allows you to store it for future use. It is a fast, simple, and secure way to connect to your virtual machine.
+- Fill in the administrator username for your VM.
+- Select **Generate new key pair**, and select **RSA SSH Format** as the SSH key type. RSA can offer better security with keys longer than 3072 bits. Give a key pair name to your SSH key.
+- In the **Inbound port rules**, select **HTTP (80)** and **SSH (22)** as the inbound ports.
 
-![Azure portal VM creation — Azure Cobalt 100 Arm64 virtual machine (D4ps_v6) alt-text#center](images/instance1.png "Figure 2: Allow inbound port rules")
+![Azure portal interface displaying the Inbound port rules configuration step for an Azure Cobalt 100 Arm64 virtual machine (D4ps_v6). The main focus is on selecting HTTP port 80 and SSH port 22 as allowed inbound ports. The wider environment is the Azure portal's virtual machine creation workflow, with a clean and organized layout. Visible text includes Inbound port rules, HTTP 80, SSH 22, and options to add or remove ports. The tone is neutral and instructional, guiding users through network security settings for the VM. alt-text#center](images/instance1.png "Allow inbound port rules")
 
-9. Click on the "Review + Create" tab and review the configuration for your virtual machine. It should look like the following:
+- Click on the **Review + Create** tab and review the configuration for your virtual machine. It should look like the following:
 
-![Azure portal VM creation — Azure Cobalt 100 Arm64 virtual machine (D4ps_v6) alt-text#center](images/ubuntu-pro.png "Figure 3: Review and Create an Azure Cobalt 100 Arm64 VM")
+![Azure portal interface displaying the Review and Create step for an Azure Cobalt 100 Arm64 virtual machine. The primary subject is the summary panel showing selected configuration details, including Ubuntu Pro 24.04 LTS as the operating system, D4ps_v6 as the VM size, Arm64 architecture, and SSH public key authentication. The wider environment is the Azure portal's virtual machine creation workflow, with a clean and organized layout. Visible text includes Review and Create, Ubuntu Pro 24.04 LTS, D4ps_v6, Arm64, SSH public key, and configuration summary fields. The tone is neutral and informative, guiding users through the final review before VM deployment. alt-text#center](images/ubuntu-pro.png "Review and create an Azure Cobalt 100 Arm64 VM")
 
-10. Finally, when you are confident about your selection, click on the "Create" button, and click on the "Download Private key and Create Resources" button.
+- Finally, when you are confident about your selection, click on the "Create" button, and click on the "Download Private key and Create Resources" button.
 
-![Azure portal VM creation — Azure Cobalt 100 Arm64 virtual machine (D4ps_v6) alt-text#center](images/instance4.png "Figure 4: Download Private key and Create Resources")
+![Azure portal VM creation — Azure Cobalt 100 Arm64 virtual machine (D4ps_v6) alt-text#center](images/instance4.png "Download private key and create resources")
 
-11. Your virtual machine should be ready and running within no time. You can SSH into the virtual machine using the private key, along with the Public IP details.
+Your virtual machine is now ready and running. To connect, use SSH with your private key and the VM's public IP address.
 
-![Azure portal VM creation — Azure Cobalt 100 Arm64 virtual machine (D4ps_v6) alt-text#center](images/final-vm.png "Figure 5: VM deployment confirmation in Azure portal")
+![Azure portal VM creation — Azure Cobalt 100 Arm64 virtual machine (D4ps_v6) alt-text#center](images/final-vm.png "VM deployment confirmation in Azure portal")
 
 {{% notice Note %}}
 
-To learn more about Arm-based virtual machine in Azure, refer to “Getting Started with Microsoft Azure” in [Get started with Arm-based cloud instances](/learning-paths/servers-and-cloud-computing/csp/azure).
+To learn more about Arm-based virtual machine in Azure, refer to *Getting Started with Microsoft Azure* in [Get started with Arm-based cloud instances](/learning-paths/servers-and-cloud-computing/csp/azure).
 
 {{% /notice %}}

content/learning-paths/servers-and-cloud-computing/kafka-azure/deploy.md

@@ -10,7 +10,7 @@ layout: learningpathall
 
 This section guides you through installing the latest version of Apache Kafka on an Ubuntu Pro 24.04 (Arm64) virtual machine running on Azure Cobalt 100. Kafka is a high-throughput, distributed event streaming platform used for real-time data pipelines and messaging applications. 
 
-### Install Java
+## Install Java
 
 Apache Kafka runs on the Java Virtual Machine (JVM), so Java must be installed before setting up Kafka. Use the following commands to update your package index and install the default JDK:
 ```console
@@ -19,7 +19,7 @@ sudo apt install -y default-jdk
 ```
 This installs the Java Development Kit (JDK), which includes the JVM, compiler, and standard libraries required for running Kafka services.
 
-### Download and Install Kafka
+## Download and install Kafka
 
 Use the following commands to download and install Apache Kafka 4.1.0 in the /opt directory, extract the archive, and set appropriate permissions for your user. This prepares your system to run Kafka without requiring elevated privileges later.
 
@@ -35,7 +35,7 @@ Kafka [3.5.0 release announcement](https://kafka.apache.org/blog#apache_kafka_35
 The [Arm Ecosystem Dashboard](https://developer.arm.com/ecosystem-dashboard/) recommends Apache Kafka version 3.5.0 as the minimum recommended on Arm platforms.
 {{% /notice %}}
 
-### Check installed Kafka version
+## Check installed Kafka version
 
 After extraction, verify that Kafka was installed successfully by checking the version: