docs: improve CRD reference intro paragraphs (#3320)

Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com>
Co-authored-by: RealAnna <89971034+RealAnna@users.noreply.github.com>

docs/docs/reference/crd-reference/analysis.md

@@ -4,10 +4,14 @@ comments: true
 
 # Analysis
 
-An `Analysis` resource customizes the templates
-that are defined in an
+An `Analysis` is a snapshot of your current application status.
+Based on your defined SLIs, it can validate that your SLOs are satisfied,
+using the data coming from your defined set of `KeptnMetricsProvider` resources.
+
+The `Analysis` resource is an instance of an
 [AnalysisDefinition](analysisdefinition.md) resource
-by identifying the time for which the analysis should be done
+which defines specific data like
+the time for which the analysis should be done
 and the appropriate values to use for variables
 that are used in the `AnalysisDefinition` query.
 

docs/docs/reference/crd-reference/analysisvaluetemplate.md

@@ -7,9 +7,8 @@ comments: true
 An `AnalysisValueTemplate` resource
 defines a Service Level Indicator (SLI),
 which identifies the data to be analyzed
-by data source to use and the query to issue.
-One Analysis can use data from multiple instances
-of multiple types of data provider.
+by a data source to use and the query to issue.
+One Analysis can use data from multiple AnalysisValueTemplates.
 
 ## Synopsis
 

docs/docs/reference/crd-reference/app.md

@@ -4,11 +4,10 @@ comments: true
 
 # KeptnApp
 
-A `KeptnApp` resource is auto-generated to list all the
+The auto-generated `KeptnApp` resource aggregates all the
 [workloads](https://kubernetes.io/docs/concepts/workloads/)
-that constitute a logical Keptn application
-and to work with the corresponding
-[KeptnAppContext](appcontext.md) resource.
+that constitute a logical Keptn application, based on the annotations made
+to the workloads.
 
 ## Synopsis
 

docs/docs/reference/crd-reference/appcontext.md

@@ -11,7 +11,7 @@ It allows you to
 
 - Add metadata and links to traces for a specific application.
   This enables you to enrich your traces with additional information that
-  you can use to understand and analyze
+  you can use to better understand and analyze
   the performance of your applications.
 
 - Define tasks and evaluations that run

docs/docs/reference/crd-reference/evaluationdefinition.md

@@ -8,7 +8,7 @@ A `KeptnEvaluationDefinition` assigns target values
 to [KeptnMetric](metric.md) queries.
 These are used as part of evaluation tasks
 that Keptn runs
-as part of pre- and post-analysis phases of a [workload](https://kubernetes.io/docs/concepts/workloads/) or application.
+as part of pre- and post-analysis phases of a `KeptnApp` or workload.
 
 ## Yaml Synopsis
 

docs/docs/reference/crd-reference/metric.md

@@ -5,13 +5,13 @@ comments: true
 # KeptnMetric
 
 A `KeptnMetric` represents a metric that is collected from a provider.
-Providing the metrics as a CR in a Kubernetes cluster
+Providing the metrics as a custom resource
 facilitates the reusability of this data across multiple components
 and allows using multiple observability platforms
 for different metrics at the same time.
 
-`KeptnMetric` CRs are also used as targets for
-[EvaluationDefinition](evaluationdefinition.md) CRs.
+`KeptnMetric` resources are also used as targets for
+[EvaluationDefinition](evaluationdefinition.md) resources.
 
 ## Yaml Synopsis
 

docs/docs/reference/crd-reference/metricsprovider.md

@@ -4,14 +4,14 @@ comments: true
 
 # KeptnMetricsProvider
 
-KeptnMetricsProvider defines an instance of the data provider
+A `KeptnMetricsProvider` resource defines an instance of a data provider
 (such as Prometheus, Dynatrace, or Datadog)
-that is used by the [KeptnMetric](metric.md) resource.
+that is used by one or more [KeptnMetric](metric.md) resources.
 
 One Keptn application can perform
 traces, evaluations, and analyses based on metrics
 from more than one data provider
-and, beginning with the v1alpha3 API version,
+and, beginning with the API version v1alpha3,
 can use more than one instance of each data provider.
 To implement this, create a `KeptnMetricsProvider` resource
 for each instance of each data provider being used,

docs/docs/reference/crd-reference/task.md

@@ -4,12 +4,13 @@ comments: true
 
 # KeptnTask
 
-Keptn uses KeptnTask resources internally
+Keptn uses `KeptnTask` resources internally
 to manage tasks (and their underlying Kubernetes Job resources)
 that are run before and after deployment of your workloads  
 (pre- and post-deployment tasks).
 You do not need to create this resource yourself except in special situations,
-like using Keptn to manage workloads that are outside of the k8s cluster.
+for instance when using Keptn to manage workloads outside the k8s cluster.
+See the [use case page](../../use-cases/non-k8s.md) for more details about this.
 
 ## Synopsis
 

docs/docs/reference/crd-reference/taskdefinition.md

@@ -20,11 +20,12 @@ Each `KeptnTaskDefinition` can use exactly one container with one runner.
 which is one of the following,
 differentiated by the `spec` section:
 
-- The `custom-runtime` runner provides
-  a standard Kubernetes application container
-  that is run as part of a Kubernetes job.
-  You define the runner, an application,
-  and its runtime dependencies.
+- The `container-runtime` runner provides
+  functionality to run
+  a standard Kubernetes container inside
+  a Kubernetes job.
+  You define the container image, and
+  the arbitrary application inside it.
   This gives you the flexibility
   to define tasks using the language and facilities of your choice,
   although it is more complicated that using one of the pre-defined runtimes.
@@ -39,8 +40,7 @@ differentiated by the `spec` section:
       to define tasks using
       [Deno](https://deno.com/)
       scripts,
-      which use a syntax similar to JavaScript and Typescript,
-      with a few limitations.
+      which use JavaScript with a few limitations.
       You can use this to specify simple actions
       without having to define a full container.
       See [runtime examples](#examples-for-deno-runtime-and-python-runtime-runners)