Update to match style guide

mscwilson · mscwilson · commit 7a37d67362da · 2025-06-12T13:19:57.000+01:00
diff --git a/tutorials/kafka-live-viewer-profiles/conclusion.md b/tutorials/kafka-live-viewer-profiles/conclusion.md
@@ -3,39 +3,39 @@ position: 4
 title: Conclusion
 ---
 
-# Conclusion
+In this tutorial, you've explored the **live viewer profiles** solution accelerator for video streaming, gaining practical insights into building, deploying, and extending real-time, event-driven architectures using Snowplow and Kafka.
 
-In this tutorial, we have explored the **live viewer profiles** solution accelerator for video streaming, gaining practical insights into building, deploying, and extending real-time, event-driven architectures using Snowplow and Kafka.
+## Understanding the process
 
-## Key Takeaways
-
-### Understanding the Process
-We successfully have built a real time system for processing event data including:
-- **Web Tracking Application** for collecting media events.
+You have successfully built a real time system for processing event data including:
+- **Web tracking application** for collecting media events
 ![Application Output](images/video.png)
-- **Snowplow Collector and Snowbridge** for event processing and forwarding.
-- **Live Viewer Backend** for managing real-time data with Kafka and DynamoDB.
-- **Live Viewer Frontend** for visualizing real-time user activity on the web tracking application.
+- **Snowplow Collector and Snowbridge** for event processing and forwarding
+- **Live Viewer back-end** for managing real-time data with Kafka and DynamoDB
+- **Live Viewer front-end** for visualizing real-time user activity on the web tracking application
 ![Live viewer frontend](images/live-viewer.png)
 
 This architecture highlights how real-time insights can be achieved using event-driven systems in a streaming context.
 
-### What We Achieved
-We explored how to:
-1. Use LocalStack to emulate AWS services for local development and testing.
-2. Launch and interact with the system components, such as the Kafka UI and LocalStack UI.
-3. View and verify the real-time event data from the browser using Snowplow's media tracking capabilities.
-4. Deploy the solution in an AWS environment using Terraform. 
+## What you achieved
+
+You explored how to:
+1. Use LocalStack to emulate AWS services for local development and testing
+2. Launch and interact with the system components, such as the Kafka UI and LocalStack UI
+3. View and verify the real-time event data from the browser using Snowplow's media tracking capabilities
+4. Deploy the solution in an AWS environment using Terraform
+
+## Practical applications
 
-### Practical Applications
 This tutorial can be extended to utilize Snowplow event data for other real-time use cases, such as:
-- Web Engagement analytics.
-- Personalized recommendations.
-- Ad performance tracking.
+- Web Engagement analytics
+- Personalized recommendations
+- Ad performance tracking
+
+## Next steps
 
-## Next Steps
-- **Extend tracking:** Extend the solution to track more granular user interactions or track on a new platform such as mobile.
-- **Extend dashboard:** Extend the Live Viewer to include information on the media being watched and the user.
-- **Replace the state store:** Replace Amazon DynamoDB with an alternative to be cloud agnostic, e.g. Google Bigtable or MongoDB.
+- **Extend tracking:** extend the solution to track more granular user interactions or track on a new platform such as mobile
+- **Extend dashboard:** extend the Live Viewer to include information on the media being watched and the user
+- **Replace the state store:** replace Amazon DynamoDB with an alternative to be cloud agnostic, e.g. Google Bigtable or MongoDB
 
-By completing this tutorial, you are equipped to harness the power of event-driven systems and Snowplow’s analytics framework to build dynamic, real-time solutions tailored to your streaming and analytics needs.
+By completing this tutorial, you're equipped to harness the power of event-driven systems and Snowplow's analytics framework to build dynamic, real-time solutions tailored to your streaming and analytics needs.
diff --git a/tutorials/kafka-live-viewer-profiles/deploy-aws-terraform.md b/tutorials/kafka-live-viewer-profiles/deploy-aws-terraform.md
@@ -3,19 +3,13 @@ position: 3
 title: Deploy on AWS with Terraform
 ---
 
-# Deploy on AWS with Terraform
+The following steps will deploy the solution accelerator to AWS using Terraform. This is an alternative to the Localstack method. There is no need to manually install [Terraform](https://www.terraform.io/). It is executed via [Docker](https://www.docker.com/) using the `terraform.sh` script.
 
-## Introduction
+## Step 0: Prerequisites
 
-The following [Steps](#steps) will deploy the solution accelerator to AWS using Terraform. There is no need to manually install [Terraform](https://www.terraform.io/). It is executed via [Docker](https://www.docker.com/) using the `terraform.sh` script.
-
-## Steps to Deploy the Application
-
-### Step 0: Prerequisites
-
-1. Open a terminal.
-2. Install **Docker** and **Docker Compose**.
-3. [Clone the project](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles) and navigate to its directory.
+1. Open a terminal
+2. Install **Docker** and **Docker Compose**
+3. [Clone the project](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles) and navigate to its directory
 ```bash
 git clone https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles.git
 ```
@@ -27,20 +21,19 @@ AWS_ACCESS_KEY_ID=xxxxxxxxxxxxxxxxxxxxx
 AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxx
 ```
 
-
-### Step 1: Initialize the Project
+## Step 1: Initialize the project
 
 ```bash
 $ ./terraform/terraform.sh init
 ```
 
-### Step 2: Create the Infrastructure
+## Step 2: Create the infrastructure
 
 ```bash
 $ ./terraform/terraform.sh apply
 ```
 
-### Step 3: Access the EC2 Instance that Runs the Apps in AWS
+## Step 3: Access the EC2 instance that runs the apps in AWS
 
 ```bash
 $ ./terraform/apps/ssh.sh
@@ -56,24 +49,25 @@ $ ./down.sh  # <- stop the Docker containers
 $ ./up.sh    # <- start the Docker containers
 ```
 
-### Step 4: Open Access to the Applications
+## Step 4: Open access to the applications
 
-Review the [LocalStack guide](/tutorials/kafka-live-viewer-profiles/quickstart-localstack) for the default configuration for each component. Open public access to the two frontend applications and the Snowplow Collector using a HTTP load balancer so that anyone can watch the video, submit events to the pipeline, and see information on concurrent users.
+Review the [LocalStack guide](/tutorials/kafka-live-viewer-profiles/quickstart-localstack) for the default configuration for each component. Open public access to the two front-end applications and the Snowplow Collector using a HTTP load balancer so that anyone can watch the video, submit events to the pipeline, and see information on concurrent users.
 
 The applications listen for HTTP traffic on the following ports
-- Web tracker front end - 3000
-- Live viewer front end - 8280
-- Snowplow collector - 9090
+- Web tracker front-end - 3000
+- Live viewer front-end - 8280
+- Snowplow Collector - 9090
+
+## Next steps
 
-## Next Steps
 - You can implement Snowplow media tracking on any [HTML5](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/media/html5/) or [YouTube](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/media/youtube/) media of your choice
-- Look into the output from Kafka and extend the Live Viewer to include information on the media being watched and the user.
-- Replace Amazon DynamoDB with an alternative to be cloud agnostic, e.g. Google Bigtable or MongoDB.
+- Look into the output from Kafka and extend the Live Viewer to include information on the media being watched and the user
+- Replace Amazon DynamoDB with an alternative to be cloud agnostic, e.g. Google Bigtable or MongoDB
 ---
 
-## Other Commands
+## Other commands
 
-### Check Versions
+### Check versions
 
 ```bash
 $ ./terraform/terraform.sh --version
@@ -87,13 +81,13 @@ on linux_amd64
 + provider registry.terraform.io/hashicorp/tls v4.0.6
 ```
 
-### Check the Terraform Plan
+### Check the Terraform plan
 
 ```bash
 $ ./terraform/terraform.sh plan
 ```
 
-### Generate a PNG Image for the Terraform Modules in This Project
+### Generate a PNG image for the Terraform modules in this project
 
 ```bash
 $ ./terraform/terraform.sh png
@@ -103,7 +97,7 @@ Current PNG image of the available modules:
 
 ![Terraform Modules](images/terraform.png)
 
-### Destroy the Infrastructure
+### Destroy the infrastructure
 
 ```bash
 $ ./terraform/terraform.sh destroy
diff --git a/tutorials/kafka-live-viewer-profiles/introduction.md b/tutorials/kafka-live-viewer-profiles/introduction.md
@@ -3,55 +3,53 @@ position: 1
 title: Introduction
 ---
 
-## About This Accelerator
-Welcome to the **live viewer profiles** solution accelerator for video streaming!
+Welcome to the **live viewer profiles** solution accelerator for video streaming.
 
 This accelerator demonstrates how to build a real-time use case leveraging **Snowplow event data** to create live viewer profiles for a video streaming site. By combining Snowplow's streaming pipeline with **Apache Kafka**, a **Java application** and **AWS DynamoDB**, the solution processes live streaming events to visualize user interactions with video content and advertisements.
 
-On the left side of the image below we have someone watching a video. Their events are sent through a Snowplow pipeline to Kafka where they are consumed and processed by an application. The result of this processing is displayed in the right window. This shows the number of active users and their current state.
+On the left side of the image below, someone is watching a video. Their events are sent through a Snowplow pipeline to Kafka where they are consumed and processed by an application. The result of this processing is displayed in the right window. This shows the number of active users and their current state.
 
 ![Application Output](images/one-viewer.png)
 
-Through this hands-on guide, you’ll learn how to build, deploy, and extend real-time, event-driven architectures using Snowplow and Kafka, enabling personalized recommendations, real-time insights, and dynamic analytics for streaming platforms. The framework is inspired by common challenges in video streaming, including tracking user behavior, ad engagement, and session activities, with the goal of maintaining up-to-date viewer profiles in DynamoDB.
+Through this hands-on guide, you'll learn how to build, deploy, and extend real-time, event-driven architectures using Snowplow and Kafka, enabling personalized recommendations, real-time insights, and dynamic analytics for streaming platforms. The framework is inspired by common challenges in video streaming, including tracking user behavior, ad engagement, and session activities, with the goal of maintaining up-to-date viewer profiles in DynamoDB.
 
 This accelerator is open source and can serve as the foundation to build practical applications like real-time viewer insights, engagement analytics, ad performance tracking, and personalized recommendations. Whether you're optimizing ad placements or enhancing viewer satisfaction, this guide equips you to unlock the full potential of Snowplow event data.
 
 Please start by reviewing how the application works in the next page on Localstack, even if you're planning to deploy with Terraform.
 
----
-
-## Solution Accelerator Code
-[**The code for this infrastructure is available on here on GitHub.**](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles)
+## Solution Accelerator code
 
----
+The code for this infrastructure is available [here on GitHub](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles).
 
 ## Architecture
 
 The solution comprises several interconnected components:
 
-- **Web Tracking Application**:
-  - A React application with a video to watch. Snowplow's media tracking has been configured to send events (e.g., play, pause, ad skipped) to the [Snowplow Collector](/docs/fundamentals).
+- **Web tracking application**:
+  - A React application with a video to watch
+  - Snowplow's media tracking has been configured to send events (e.g., play, pause, ad skipped) to the [Snowplow Collector](/docs/fundamentals)
   - Code available in [tracker-frontend](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles/tree/main/tracker-frontend) folder in GitHub
 
 - **Snowplow Collector**:
-  - Collects and forwards events via [Stream Enrich](/docs/fundamentals) and Kinesis to [Snowbridge](/docs/destinations/forwarding-events/snowbridge).
+  - Collects and forwards events via [Stream Enrich](/docs/fundamentals) and Kinesis to [Snowbridge](/docs/destinations/forwarding-events/snowbridge)
 
 - **Snowplow Snowbridge**:
-  - Publishes events to Kafka for the Live Viewer Backend to consume
+  - Publishes events to Kafka for the Live Viewer back-end to consume
 
-- **Live Viewer Backend**:
-  - A Java application which processes events from Kafka, stores the data in DynamoDB, and generates JSON state data for the Live Viewer Frontend
+- **Live Viewer back-end**:
+  - A Java application which processes events from Kafka, stores the data in DynamoDB, and generates JSON state data for the Live Viewer front-end
   - Code available in [live-viewer-backend](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles/tree/main/live-viewer-backend) folder in GitHub
 
-- **Live Viewer Frontend**:
-  - A HTML website which displays the state of users currently watching the video.
+- **Live Viewer front-end**:
+  - A HTML website which displays the state of users currently watching the video
   - Code available in [live-viewer-frontend](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles/tree/main/live-viewer-frontend) folder in GitHub
 
-The following diagram maps out where each component sits in the end to end communication flow.
+The following diagram maps out where each component sits in the end-to-end communication flow.
 ![Architecture Diagram](images/architecture.png)
 
-### Components & Configuration
-The following files in the [GitHub repository](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles) can be used  to configure the project's components.
+### Components and configuration
+
+The following files in the [GitHub repository](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles) can be used to configure the project's components:
 - **Snowplow components**: `docker/compose.snowplow.yaml`
 - **Kafka infrastructure**: `docker/compose.kafka.yaml`
 - **Application components**: `docker/compose.apps.yaml`
diff --git a/tutorials/kafka-live-viewer-profiles/quickstart-localstack.md b/tutorials/kafka-live-viewer-profiles/quickstart-localstack.md
@@ -3,19 +3,18 @@ position: 2
 title: Quickstart with Localstack
 ---
 
-# Quickstart with Localstack
+The following steps will deploy the solution accelerator using Localstack.
 
-## Steps to Run the Application
+## Step 0: Prerequisites
 
-### Step 0: Prerequisites
-
-1. Open a terminal.
-2. Install **Docker** and **Docker Compose**.
-3. [Clone the project](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles) and navigate to its directory.
+1. Open a terminal
+2. Install **Docker** and **Docker Compose**
+3. [Clone the project](https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles) and navigate to its directory
 ```bash
 git clone https://github.com/snowplow-industry-solutions/kafka-live-viewer-profiles.git
 ```
-4. Create a `.env` file based on `./docker/.env.example`. You can leave the AWS variables as placeholders when using Localstack
+4. Create a `.env` file based on `./docker/.env.example`
+5. You can leave the AWS variables as placeholders when using Localstack
 ```bash
 ACCEPT_LICENSE="true"
 AWS_REGION=eu-west-2
@@ -24,20 +23,20 @@ AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxx
 AWS_ENDPOINT_URL=http://localstack:4566
 ```
 
-### Step 1: Start the Containers
+## Step 1: Start the containers
 
 Run the following command to download and run everything in Docker:
 
 ```bash
 ./docker/up.sh
 ```
-Details on everything that is installed can be found in [architecture](/tutorials/kafka-live-viewer-profiles/introduction#architecture)
+Details on everything that's installed can be found in the [architecture](/tutorials/kafka-live-viewer-profiles/introduction#architecture) section on the previous page.
 
 **Tips:**
-- Use `Ctrl+C` to stop services but keep containers running.
-- Pass service-specific options to `./docker/up.sh` (e.g., `./docker/up.sh kafka-services`).
+- Use `Ctrl+C` to stop services but keep containers running
+- Pass service-specific options to `./docker/up.sh` (e.g., `./docker/up.sh kafka-services`)
 
-### Step 2: Open the Web Tracking Frontend
+## Step 2: Open the web tracking front-end
 
 Visit [http://localhost:3000](http://localhost:3000) to configure the Stream Collector endpoint and start tracking events. Enter the Collector URL: `localhost:9090` and click `Create tracker`.
 
@@ -51,38 +50,39 @@ You must keep this window open with the video playing because everything here is
 
 ![Video playing on the website](images/video.png)
 
-### Step 3: Open the Live Viewer Frontend
+## Step 3: Open the Live Viewer front-end
 
 Open [http://localhost:8280](http://localhost:8280) in a separate window. This will display the active users and their current state (e.g. watching video, watching advertisement, paused).
 
 ![Live viewer frontend](images/live-viewer.png)
 
 Congratulations! You have successfully run the accelerator to stream web behavior through Snowplow and Kafka to a real-time dashboard.
 
-## Next Steps
+## Next steps
+
 - You can implement Snowplow media tracking on any [HTML5](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/media/html5/) or [YouTube](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/media/youtube/) media of your choice
-- Look into the output from Kafka and extend the Live Viewer to include information on the media being watched and the user.
-- Use our supplied Terraform in the next section to run this on AWS and make it publicly available.
+- Look into the output from Kafka and extend the Live Viewer to include information on the media being watched and the user
+- Use the supplied Terraform in the next section to run this on AWS and make it publicly available
 
-## Other Things You Can Do
+## Other things you can do
 
 ### View Events in Kafka UI
 
 Access [http://localhost:8080](http://localhost:8080) to review events within the Kafka UI.
 
-### Manage Containers with LazyDocker
+### Manage containers with LazyDocker
 
 Run the following command to manage containers visually:
 
 ```bash
 sudo ./docker/lazy.sh
 ```
 
-### Inspect Infrastructure with LocalStack UI
+### Inspect infrastructure with LocalStack UI
 
 Visit the [LocalStack UI](https://app.localstack.cloud/) to inspect infrastructure components such as Kinesis and DynamoDB. Please note that a LocalStack account is required to view this.
 
-## Cleaning Up
+## Cleaning up
 
 ### Stop the containers
 
@@ -92,12 +92,12 @@ Shut down all running containers:
 ./docker/down.sh
 ```
 
-### Clean Up and Delete
+### Clean up and delete
 
 To remove all containers and images, use:
 
 ```bash
 ./docker/clean.sh
 ```
 
-**Warning**: This command will delete all generated data.
+This command will delete all generated data.
