fix(docs): adding Keptn doc suggestions (#1867)

* Adding Keptn doc suggestions

* Fix minor markdown issues

* Apply suggestions from code review

Co-authored-by: Julianne Fermi <julianne@kubeshop.io>

* Removing analytics

* Adding Tracetest explanation

Co-authored-by: Julianne Fermi <julianne@kubeshop.io>

examples/keptn-integration/README.md

@@ -1,5 +1,7 @@
 # Running Tracetest with Keptn
 
+[Tracetest](https://tracetest.io/) is a testing tool based on OpenTelemetry that permits you to test your distributed application. It allows you to use your trace data generated on your OpenTelemetry tools to check and assert if your application has the desired behavior defined by your test definitions.
+
 [Keptn](https://keptn.sh/) is a powerful tool to automate the lifecycle of your application running on Kubernetes. One of the tasks that we can do on `keptn` is to test an application and see if it is healthy and ready to be used by your users.
 
 By using the Keptn [Job Executor Service](https://github.com/keptn-contrib/job-executor-service) plugin, we can upload a Tracetest test definition and a CLI configuration to a service and run a test using the following job:
@@ -31,25 +33,32 @@ actions:
 
 ## Quickstart
 
-Here we will show how to use Tracetest to do these tests and help in your delivery and testing workflows. 
+Here we will show how to use Tracetest to do these tests and help in your delivery and testing workflows using the [Pokeshop](https://docs.tracetest.io/pokeshop/) example, available at address `http://demo-pokemon-api.demo` at Kubernetes.
 
-### Assumptions
+### Prerequisites
 
-1. We are using the [Pokeshop](https://docs.tracetest.io/pokeshop/) example, exposed on `http://demo-pokemon-api.demo`.
-2. Tracetest is installed in `tracetest` namespace in that cluster.
-3. We are considering that Keptn is [already installed](https://keptn.sh/docs/1.0.x/install/) with the [Job Executor Service](https://github.com/keptn-contrib/job-executor-service) plugin on your Kubernetes cluster and that you have the [CLI](https://keptn.sh/docs/1.0.x/install/cli-install/) installed on your machine and already [authenticated](https://keptn.sh/docs/1.0.x/install/authenticate-cli-bridge/) with Keptn API.
-
-### 1. Setup a project and a service
+On your Kubernetes cluster you should have:
+
+1. `Keptn 1.0.x` [installed](https://keptn.sh/docs/1.0.x/install/)
+2. `Job Executor Service 0.3.x` [installed](https://github.com/keptn-contrib/job-executor-service/blob/main/docs/INSTALL.md)
+3. `Tracetest` server [installed](https://docs.tracetest.io/deployment/kubernetes) on `tracetest` namespace 
+
+On your machine you should have:
+
+1. `Keptn CLI` [installed](https://keptn.sh/docs/1.0.x/install/cli-install/)
+2. and already [authenticated](https://keptn.sh/docs/1.0.x/install/authenticate-cli-bridge/) with Keptn API.
+
+With everything set up, we will start configuring Keptn and Tracetest.
+
+### 1. Setup a project and a service.
 
 Keptn works with [concepts](https://keptn.sh/docs/concepts/glossary/) of a Project (element to maintain multiple services forming an application in stages) and a Service (smallest deployable unit and is deployed in all project stages according to the order).
-Usually, these resources are managed by Keptn during Sequences (a set of tasks for realizing a delivery or operations process). The following is an example of a sequence of **Deploying**** a system that contains 3 tasks:
-1. Update a service - a set of services in a namespace.
-2. Run tests to see if everything is working fine.
-3. Change traffic to this new set of services.
-
-To integrate Tracetest with Keptn, we recommend setting up a task that will invoke Tracetest to run tests on these services.
+
+Usually, these resources are managed by Keptn during Sequences (a set of tasks for realizing a delivery or operations process). In this example, we will create a sequence and run a Tracetest test in a system, once the sequence is triggered.
 
-In our example, we are setting up a project through the CLI by first defining a `shipyard` file called [`shipyard.yaml`](./shipyard.yaml) for our project:
+To do that, we will do the following steps:
+
+1. Create a skeletal [`shipyard.yaml`](./shipyard.yaml) file with the following content:
 ```yaml
 apiVersion: "spec.keptn.sh/0.2.2"
 kind: "Shipyard"
@@ -63,31 +72,30 @@ spec:
          tasks:
            - name: "test-services"
 ```
- 
-And then creating a project `keptn-tracetest-integration` with it:
+
+2. Create a new `keptn-tracetest-integration` project using that `shipyard` file:
 ```sh
 keptn create project keptn-tracetest-integration -y -s shipyard.yaml
 ```
 
 **Note:** Keptn may ask you to have a Git repository for this project to enable GitOps. If so, you need to create an empty Git repository and a Git token and pass it through the flags `--git-remote-url`, `-`-git-user`, and `--`git-token`. More details about this setup can be seen on [Keptn docs/Git-based upstream](https://keptn.sh/docs/1.0.x/manage/git_upstream).
 
-After that, we can create a service `pokeshop` for this project by executing:
+3. Create a `pokeshop` service:
 ```sh
 keptn create service pokeshop --project keptn-tracetest-integration -y
 ```
 
-### 2. Add Tracetest files and job files as resources of a service
+### 2. Add Tracetest files and job files as resources of a service.
 
-After creating a service, we will set up a job associated with the `pokeshop` service and the task event `test-services`.
+Now, we will set up a job associated with the `pokeshop` service, listening to the task event `test-services`:
 
-First, we will create a config file for the Tracetest CLI, identifying which instance of Tracetest should run the tests. The file should be saved in your current directory with the name [`tracetest-cli-config.yaml`](./tracetest-cli-config.yaml):
+1. Create the [`tracetest-cli-config.yaml`](./tracetest-cli-config.yaml) configuration file for the Tracetest CLI in your current directory, identifying the Tracetest instance that should run the tests:
 ```yaml
 scheme: http
 endpoint: tracetest.tracetest.svc.cluster.local:11633
-analyticsEnabled: false
 ```
- 
-Then, we will create a Tracetest test definition file in your current directory called [`test-definition.yaml`](./test-definition.yaml):
+
+2. Create the [`test-definition.yaml`](./test-definition.yaml) Tracetest test definition in your current directory:
 ```yaml
 type: Test
 spec:
@@ -108,13 +116,15 @@ spec:
     - attr:tracetest.span.duration < 500ms
 ```
 
-Now we will add these files as resources for the service `pokeshop` on Keptn with the following command:
+3. Add these files as resources for the `pokeshop` service:
 ```sh
 keptn add-resource --project keptn-tracetest-integration --service pokeshop --stage production --resource test-definition.yaml --resourceUri data/test-definition.yaml
 keptn add-resource --project keptn-tracetest-integration --service pokeshop --stage production --resource tracetest-cli-config.yaml --resourceUri data/tracetest-cli-config.yaml
 ```
-
-These files will be located in the folder `data` and will be injected into our Keptn job that we will set up in the next step. To that, we will set up a job definition YAML to run Tracetest every time that an event of `test-services` happens. This file will be named [`job-config.yaml`](./job-config.yaml) and will listen for the event `sh.keptn.event.test-services.triggered` (event emitted by the `test-services` task on the `deployment` sequence defined in our project):
+
+These files will be located in the folder `data` and will be injected into our Keptn job that we will set up in the next step.
+
+4. Create [`job-config.yaml`](./job-config.yaml):
 ```yaml
 apiVersion: v2
 actions:
@@ -137,17 +147,18 @@ actions:
         - --definition
         - /keptn/data/test-definition.yaml
         - --wait-for-result
-
 ```
-
-Finally, we will add this job as a resource on Keptn:
+
+This job will run Tracetest every time an event of `test-services` happens, listening to the event `sh.keptn.event.test-services.triggered` (event emitted by the `test-services` task on the `test-sequence` sequence).
+
+5. Add this job as a resource on Keptn:
 ```sh
 keptn add-resource --project keptn-tracetest-integration --service pokeshop --stage production --resource job-config.yaml --resourceUri job/config.yaml
 ```
 
-### 3. Setup Job Executor Service to see events emitted by the test step
+### 3. Setup Job Executor Service to see events emitted by the test step.
 
-To guarantee that our job will be called by Keptn when we execute the `deployment` sequence, we need to configure the integration `Job Executor Service` on `keptn-tracetest-integration` project to listen to `sh.keptn.event.test-services.triggered` events. We can do that only through the Keptn Bridge (their Web UI), by going to our project, choosing the `Settings` option, and later `Integrations``.
+To guarantee that our job will be called by Keptn when we execute the `deployment` sequence, we need to configure the integration `Job Executor Service` on `keptn-tracetest-integration` project to listen to `sh.keptn.event.test-services.triggered` events. We can do that only through the Keptn Bridge (their Web UI), by going to our project, choosing the `Settings` option, and later `Integrations`.
 
 Choose the `job-executor-service` integration, and add a subscription to the event `sh.keptn.event.test-services.triggered` and the project `keptn-tracetest-integration`.
 

examples/keptn-integration/tracetest-cli-config.yaml

@@ -1,3 +1,2 @@
 scheme: http
 endpoint: tracetest.tracetest.svc.cluster.local:11633
-analyticsEnabled: false