v0.11 Doc Updates Part 4 (#2465)

General Updates for the remainder of the docs.
kubeshop · May 1, 2023 · c133ffb · c133ffb
1 parent 6852747
commit c133ffb
Show file tree

Hide file tree

Showing 12 changed files with 35 additions and 35 deletions.
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -13,27 +13,27 @@ Tracetest allows you to quickly build integration and end-to-end tests, powered
 
 ## In a Nutshell
 
-Tracetest uses your existing [OpenTelemetry](https://opentelemetry.io/docs/getting-started/) traces to power trace-based testing with assertions against your trace data at every point of the request transaction. You only need to point Tracetest to your existing trace data source, or send traces to Tracetest directly!
+Tracetest uses your existing [OpenTelemetry](https://opentelemetry.io/docs/getting-started/) traces to power trace-based testing with assertions against your trace data at every point of the request transaction. You only need to point Tracetest to your existing trace data source or send traces to Tracetest directly!
 
 We make it possible to:
 
 - Define tests and assertions against every single microservice that a request goes through.
-- Use your preferred trace back-end, like Jaeger or Tempo, or OpenTelemetry Collector.
+- Use your preferred trace back-end, like Jaeger or Tempo or OpenTelemetry Collector.
 - Define multiple transaction triggers, such as a GET against an API endpoint, a GRPC request, etc.
 - Return both the response data and a full trace.
-- Define assertions against both the response and trace data, ensuring both your response and the underlying processes worked correctly, quickly, and without errors.
+- Define assertions against both the response and trace data, ensuring both your response and the underlying processes worked correctly, quickly and without errors.
 - Save tests.
 - Run the tests manually or via CI build jobs with the Tracetest CLI.
 
-New to trace-based testing? Read more about the concepts, [here](./concepts/what-is-trace-based-testing).
+New to trace-based testing? Read more about the concepts [here](./concepts/what-is-trace-based-testing).
 
 ## Prerequisites
 
 You need to add [OpenTelemetry instrumentation](https://opentelemetry.io/docs/instrumentation/) to your code and configure sending traces to a trace data store, or Tracetest directly, to benefit from Tracetest's trace-based testing.
 
 ## Who Uses Tracetest?
 
-Our users are typically developers or QA engineers building distributed systems with microservices using back-end languages like Go, Rust, Node.js, and Python.
+Our users are typically developers or QA engineers building distributed systems with microservices using back-end languages like Go, Rust, Node.js and Python.
 
 Tracetest enables you to write detailed trace-based tests, primarily:
 

diff --git a/docs/docs/live-examples/opentelemetry-store/overview.md b/docs/docs/live-examples/opentelemetry-store/overview.md
@@ -3,8 +3,8 @@
 This system implements an Astronomy shop in a set of microservices in different languages with OpenTelemetry enabled, intended to be used as an example of OpenTelemetry instrumentation and observability.
 
 - **Source Code**: https://github.com/open-telemetry/opentelemetry-demo
-- **Running it Locally**: [instructions](https://github.com/open-telemetry/opentelemetry-demo/blob/main/docs/docker_deployment.md#run-docker-compose)
-- **Running on Kubernetes**: [instructions](https://github.com/open-telemetry/opentelemetry-demo/blob/main/docs/kubernetes_deployment.md)
+- **Running it Locally**: [Instructions](https://github.com/open-telemetry/opentelemetry-demo/blob/main/docs/docker_deployment.md#run-docker-compose)
+- **Running on Kubernetes**: [Instructions](https://github.com/open-telemetry/opentelemetry-demo/blob/main/docs/kubernetes_deployment.md)
 
 ## Running with Tracetest
 
@@ -13,7 +13,7 @@ To run the this demo locally with Tracetest, first clone OpenTelemetry demo repo
 git clone https://github.com/open-telemetry/opentelemetry-demo.git
 ```
 
-And then, run on that folder:
+And then, run in that folder:
 ```sh
 docker compose up --no-build
 ```
@@ -26,14 +26,14 @@ After that, Tracetest will start on [http://localhost:11633](http://localhost:11
 
 ## Use Cases
 
-- [Add item into shopping cart](./use-cases/add-item-into-shopping-cart.md): Simulate a user choosing an item and adding it to the shopping cart
-- [Check shopping cart content](./use-cases/check-shopping-cart-contents.md): Simulate a user choosing different products and checking the shopping cart later 
-- [Checkout](./use-cases/checkout.md): Simulates a user choosing a product and later doing a checkout of that product, with billing and shipping info
-- [Get recommended products](./use-cases/get-recommended-products.md): Simulates a user querying for recommended products
+- [Add item into shopping cart](./use-cases/add-item-into-shopping-cart.md): Simulate a user choosing an item and adding it to the shopping cart.
+- [Check shopping cart content](./use-cases/check-shopping-cart-contents.md): Simulate a user choosing different products and checking the shopping cart later. 
+- [Checkout](./use-cases/checkout.md): Simulates a user choosing a product and later doing a checkout of that product, with billing and shipping info.
+- [Get recommended products](./use-cases/get-recommended-products.md): Simulates a user querying for recommended products.
 
 ## System Architecture
 
 This demonstration environment consists of a series of microservices, handling each aspect of the store, such as Product Catalog, Payment, Currency, etc.
 
-A detailed description of these services can be seen [here](https://github.com/open-telemetry/opentelemetry-demo/tree/main/docs#service-documentation)
-and the architecture diagrams can be seen [here](https://github.com/open-telemetry/opentelemetry-demo/blob/main/docs/current_architecture.md).
+A detailed description of these services can be seen [here](https://opentelemetry.io/docs/demo/services/)
+and the architecture diagrams can be seen [here](https://opentelemetry.io/docs/demo/architecture/).
diff --git a/...docs/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart.md b/...docs/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart.md
@@ -41,7 +41,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that
 
 ### Traces
 
-Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC), and database calls:
+Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC) and database calls:
 ![](../images/add-item-into-shopping-cart-trace.png)
 
 ### Assertions

diff --git a/docs/docs/live-examples/opentelemetry-store/use-cases/checkout.md b/docs/docs/live-examples/opentelemetry-store/use-cases/checkout.md
@@ -65,7 +65,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that
 
 ### Traces
 
-Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC), and database calls:
+Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC) and database calls:
 ![](../images/checkout-trace.png)
 
 ### Assertions

diff --git a/docs/docs/live-examples/opentelemetry-store/use-cases/get-recommended-products.md b/docs/docs/live-examples/opentelemetry-store/use-cases/get-recommended-products.md
@@ -38,7 +38,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that
 
 ### Traces
 
-Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC), and database calls:
+Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC) and database calls:
 ![](../images/get-recommended-products-trace.png)
 
 ### Assertions

diff --git a/docs/docs/live-examples/opentelemetry-store/use-cases/user-purchasing-products.md b/docs/docs/live-examples/opentelemetry-store/use-cases/user-purchasing-products.md
@@ -24,7 +24,7 @@ We can do that by creating the tests and transactions through the Web UI or usin
 
 ### Mapping Environment Variables 
 
-The first thing that we need to think about is to map the variables are needed in this process. At first glance, we can identify the vars to the API address and the user ID:
+The first thing that we need to think about is to map the variables that are needed in this process. At first glance, we can identify the vars to the API address and the user ID:
 With these variables, we can create the following definition file as saving as `user-buying-products.env`:
 
 ```sh
@@ -90,7 +90,7 @@ spec:
     - attr:tracetest.selected_spans.count >= 1
 ```
 
-After that, we will [Check Shopping Cart Contents](./check-shopping-cart-contents.md) (on `check-shopping-cart-contents.yaml`), simulating a user validating its products before finishing its purchase:
+After that, we will [Check Shopping Cart Contents](./check-shopping-cart-contents.md) (on `check-shopping-cart-contents.yaml`), simulating a user validating the products selected before finishing the purchase:
 
 ```yaml
 type: Test

diff --git a/docs/docs/live-examples/pokeshop/overview.md b/docs/docs/live-examples/pokeshop/overview.md
@@ -2,13 +2,13 @@
 
 As a testing ground, the team at Tracetest has implemented a sample instrumented API around the [PokeAPI](https://pokeapi.co/).
 
-The idea is to have a microservice-divided system that behaves like a typical scenario by having async processes ([RabbitMQ](https://www.rabbitmq.com/)), cache layers ([Redis](https://redis.io/)), database storage ([Postgres](https://www.postgresql.org/)), and simple CRUD interfaces for Pokemons.
+The idea is to have a microservice-divided system that behaves like a typical scenario by having async processes ([RabbitMQ](https://www.rabbitmq.com/)), cache layers ([Redis](https://redis.io/)), database storage ([Postgres](https://www.postgresql.org/)) and simple CRUD interfaces for Pokemons.
 
-With this, users can get familiar with the Tracetest tool by focusing on creating assertions, visualizing the trace, and identifying the different data that comes from the Collector ([Jaeger](https://www.jaegertracing.io/)). Users will learn about basic instrumentation practices like what tools to use, what data to send, when, and what suggested standards need to be followed.
+With this, users can get familiar with the Tracetest tool by focusing on creating assertions, visualizing the trace and identifying the different data that comes from the Collector ([Jaeger](https://www.jaegertracing.io/)). Users will learn about basic instrumentation practices: what tools to use, what data to send, when, and what suggested standards need to be followed.
 
 - **Source Code**: https://github.com/kubeshop/pokeshop
-- **Running it locally**: [instructions](https://github.com/kubeshop/pokeshop/blob/master/docs/installing.md#run-it-locally)
-- **Running on Kubernetes**: [instructions](https://github.com/kubeshop/pokeshop/blob/master/docs/installing.md#run-on-a-kubernetes-cluster)
+- **Running it locally**: [Instructions](https://github.com/kubeshop/pokeshop/blob/master/docs/installing.md#run-it-locally)
+- **Running on Kubernetes**: [Instructions](https://github.com/kubeshop/pokeshop/blob/master/docs/installing.md#run-on-a-kubernetes-cluster)
 
 ## Use Cases
 

diff --git a/docs/docs/live-examples/pokeshop/use-cases/add-pokemon.md b/docs/docs/live-examples/pokeshop/use-cases/add-pokemon.md
@@ -49,7 +49,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that
 
 ### Traces
 
-Running these tests for the first time will create an Observability trace like the image above, where you can see spans for the API call, validation (an API internal operation), and database calls:
+Running these tests for the first time will create an Observability trace like the image above, where you can see spans for the API call, validation (an API internal operation) and database calls:
 ![](../images/add-pokemon-trace.png)
 
 ### Assertions
@@ -66,7 +66,7 @@ Now you can validate this entire use case.
 
 ### Test Definition
 
-If you want to replicate this entire test on Tracetest see by yourself, you can replicate these steps on our Web UI or using our CLI, saving the following test definition as the file `test-definition.yml` and later running:
+If you want to replicate this entire test on Tracetest, you can replicate these steps on our Web UI or using our CLI, saving the following test definition as the file `test-definition.yml` and later running:
 
 ```sh
 tracetest test run -d test-definition.yml --wait-for-results

diff --git a/docs/docs/live-examples/pokeshop/use-cases/get-pokemon-by-id.md b/docs/docs/live-examples/pokeshop/use-cases/get-pokemon-by-id.md
@@ -1,6 +1,6 @@
 # Pokeshop API - Get Pokemon by ID
 
-This use case retrieves a specific Pokemon from the cache if it is cached, or from the database (Postgres) also populating the cache. The idea of this query is to showcase a straightforward scenario, where the API layer receives a request from the outside and needs to evaluate a different behavior depending of its dependencies.
+This use case retrieves a specific Pokemon from the cache if it is cached or from the database (Postgres) also populating the cache. The idea of this query is to showcase a straightforward scenario, where the API layer receives a request from the outside and needs to evaluate a different behavior depending of its dependencies.
 
 ```mermaid
 sequenceDiagram

diff --git a/docs/docs/live-examples/pokeshop/use-cases/import-pokemon.md b/docs/docs/live-examples/pokeshop/use-cases/import-pokemon.md
@@ -1,6 +1,6 @@
 # Pokeshop API - Import Pokemon
 
-This use case showcases a more complex scenario involving an async process. Usually, when working with microservices, there are use cases where some of the processing needs to happen asynchronously, for example, when triggering a user notification, generating reports, or processing a payment order. With this endpoint, we provide an example of how users can implement trace-based testing for such scenarios.
+This use case showcases a more complex scenario involving an async process. Usually, when working with microservices, there are use cases where some of the processing needs to happen asynchronously, for example, when triggering a user notification, generating reports or processing a payment order. With this endpoint, we provide an example of how users can implement trace-based testing for such scenarios.
 
 Here the process is split into two phases: 
 1. An API call that enqueues an import request to a queue.
@@ -69,7 +69,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that
 
 ### Traces
 
-Running these tests for the first time will create an Observability trace like the image above, where you can see spans for the API call, the queue messaging, the PokeAPI (external API) call, and database calls. One interesting thing about this trace is that **you can observe the entire use case, end to end**:
+Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API call, the queue messaging, the PokeAPI (external API) call and database calls. One interesting thing about this trace is that **you can observe the entire use case, end to end**:
 
 ![](../images/import-pokemon-trace.png)
 

diff --git a/docs/docs/live-examples/pokeshop/use-cases/list-pokemon.md b/docs/docs/live-examples/pokeshop/use-cases/list-pokemon.md
@@ -46,7 +46,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that
 
 ### Traces
 
-Running these tests for the first time will create an Observability trace like the image above, where you can see spans for the API call and database calls:
+Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API call and database calls:
 ![](../images/list-pokemons-trace.png)
 
 ### Assertions

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -452,7 +452,7 @@ const sidebars = {
         {
           type: "doc",
           id: "examples-tutorials/recipes/running-tracetest-with-testkube",
-          label: "Tracetest and Testkube - Running scheduled trace-based tests",
+          label: "Tracetest and Testkube - Running Scheduled Trace-based Tests",
         },
       ],
     },
@@ -513,12 +513,12 @@ const sidebars = {
                 {
                   type: "doc",
                   id: "live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart",
-                  label: "Add item into shopping cart",
+                  label: "Add Item into Shopping Cart",
                 },
                 {
                   type: "doc",
                   id: "live-examples/opentelemetry-store/use-cases/check-shopping-cart-contents",
-                  label: "Check shopping cart contents",
+                  label: "Check Shopping Cart Contents",
                 },
                 {
                   type: "doc",
@@ -528,12 +528,12 @@ const sidebars = {
                 {
                   type: "doc",
                   id: "live-examples/opentelemetry-store/use-cases/get-recommended-products",
-                  label: "Get recommended products",
+                  label: "Get Recommended Products",
                 },
                 {
                   type: "doc",
                   id: "live-examples/opentelemetry-store/use-cases/user-purchasing-products",
-                  label: "User purchasing products",
+                  label: "User Purchasing Products",
                 },
               ],
             },
@@ -543,7 +543,7 @@ const sidebars = {
     },
     {
       type: "link",
-      label: "Tracetest Open API definition",
+      label: "Tracetest Open API Definition",
       href: "/openapi",
     },
   ],