Improve Docs for readability (#964)

grafana · Dec 5, 2024 · 3c9c72e · 3c9c72e
1 parent 474e1e5
commit 3c9c72e
Show file tree

Hide file tree

Showing 22 changed files with 211 additions and 336 deletions.
diff --git a/charts/feature-annotation-autodiscovery/README.md b/charts/feature-annotation-autodiscovery/README.md
@@ -8,10 +8,14 @@
 ![Version: 1.0.0](https://img.shields.io/badge/Version-1.0.0-informational?style=flat-square) ![AppVersion: 1.0.0](https://img.shields.io/badge/AppVersion-1.0.0-informational?style=flat-square)
 Gathers metrics automatically based on Kubernetes Pod and Service annotations
 
-The annotation-based autodiscovery feature makes it easy to add scrape targets. With this feature enabled, any
-Kubernetes Pods or Services with the `k8s.grafana.com/scrape` annotation set to `true` will be automatically discovered
-and scraped by the collector. There are several other annotations that can be used to customize the behavior of the
-scrape configuration, such as:
+The annotation-based autodiscovery feature makes it easy to add scrape targets.
+
+## How it works
+
+With this feature enabled, any Kubernetes Pods or Services with the `k8s.grafana.com/scrape` annotation set to `true` will be automatically discovered
+and scraped by the collector.
+
+You can use several other annotations to customize the behavior of the scrape configuration, such as:
 
 *   `k8s.grafana.com/job`: The value to use for the `job` label.
 *   `k8s.grafana.com/instance`: The value to use for the `instance` label.
@@ -23,14 +27,11 @@ scrape configuration, such as:
 
 ## Testing
 
-This chart contains unit tests to verify the generated configuration. A hidden value, `deployAsConfigMap`, will render
-the generated configuration into a ConfigMap object. This ConfigMap is not used during regular operation, but it is
-useful for showing the outcome of a given values file.
+This chart contains unit tests to verify the generated configuration. The hidden value `deployAsConfigMap` will render the generated configuration into a ConfigMap object. While this ConfigMap is not used during regular operation, you can use it to show the outcome of a given values file.
 
-The unit tests use this to create an object with the configuration that can be asserted against. To run the tests, use
-`helm test`.
+The unit tests use this ConfigMap to create an object with the configuration that can be asserted against. To run the tests, use `helm test`.
 
-Actual integration testing in a live environment should be done in the main [k8s-monitoring](../k8s-monitoring) chart.
+Be sure perform actual integration testing in a live environment in the main [k8s-monitoring](../k8s-monitoring) chart.
 
 ## Maintainers
 

diff --git a/charts/feature-annotation-autodiscovery/README.md.gotmpl b/charts/feature-annotation-autodiscovery/README.md.gotmpl
@@ -9,10 +9,14 @@
 {{ template "chart.description" . }}
 {{ template "chart.homepageLine" . }}
 
-The annotation-based autodiscovery feature makes it easy to add scrape targets. With this feature enabled, any
-Kubernetes Pods or Services with the `k8s.grafana.com/scrape` annotation set to `true` will be automatically discovered
-and scraped by the collector. There are several other annotations that can be used to customize the behavior of the
-scrape configuration, such as:
+The annotation-based autodiscovery feature makes it easy to add scrape targets. 
+
+## How it works
+
+With this feature enabled, any Kubernetes Pods or Services with the `k8s.grafana.com/scrape` annotation set to `true` will be automatically discovered
+and scraped by the collector. 
+
+You can use several other annotations to customize the behavior of the scrape configuration, such as:
 
 *   `k8s.grafana.com/job`: The value to use for the `job` label.
 *   `k8s.grafana.com/instance`: The value to use for the `instance` label.
@@ -24,14 +28,11 @@ scrape configuration, such as:
 
 ## Testing
 
-This chart contains unit tests to verify the generated configuration. A hidden value, `deployAsConfigMap`, will render
-the generated configuration into a ConfigMap object. This ConfigMap is not used during regular operation, but it is
-useful for showing the outcome of a given values file.
+This chart contains unit tests to verify the generated configuration. The hidden value `deployAsConfigMap` will render the generated configuration into a ConfigMap object. While this ConfigMap is not used during regular operation, you can use it to show the outcome of a given values file.
 
-The unit tests use this to create an object with the configuration that can be asserted against. To run the tests, use
-`helm test`.
+The unit tests use this ConfigMap to create an object with the configuration that can be asserted against. To run the tests, use `helm test`.
 
-Actual integration testing in a live environment should be done in the main [k8s-monitoring](../k8s-monitoring) chart.
+Be sure perform actual integration testing in a live environment in the main [k8s-monitoring](../k8s-monitoring) chart.
 
 {{ template "chart.maintainersSection" . }}
 <!-- markdownlint-disable no-bare-urls -->

diff --git a/charts/feature-application-observability/README.md b/charts/feature-application-observability/README.md
@@ -8,19 +8,22 @@
 ![Version: 1.0.0](https://img.shields.io/badge/Version-1.0.0-informational?style=flat-square) ![AppVersion: 1.0.0](https://img.shields.io/badge/AppVersion-1.0.0-informational?style=flat-square)
 Gathers application data
 
-The Application Observability feature enables the collection of application telemetry data. Enabling this feature
-requires enabling one or more receivers where data will be sent from the application.
+The Application Observability feature enables the collection of application telemetry data.
+
+## Before enabling
+
+Before you enable this feature, you must enable one or more receivers where data will be sent from the application.
 
 ## Testing
 
-This chart contains unit tests to verify the generated configuration. A hidden value, `deployAsConfigMap`, will render
-the generated configuration into a ConfigMap object. This ConfigMap is not used during regular operation, but it is
-useful for showing the outcome of a given values file.
+This chart contains unit tests to verify the generated configuration. The hidden value `deployAsConfigMap` will render
+the generated configuration into a ConfigMap object. While this ConfigMap is not used during regular operation, you can use
+it to show the outcome of a given values file.
 
-The unit tests use this to create an object with the configuration that can be asserted against. To run the tests, use
+The unit tests use this ConfigMap to create an object with the configuration that can be asserted against. To run the tests, use
 `helm test`.
 
-Actual integration testing in a live environment should be done in the main [k8s-monitoring](../k8s-monitoring) chart.
+Be sure perform actual integration testing in a live environment in the main [k8s-monitoring](../k8s-monitoring) chart.
 
 ## Maintainers
 

diff --git a/charts/feature-application-observability/README.md.gotmpl b/charts/feature-application-observability/README.md.gotmpl
@@ -9,19 +9,22 @@
 {{ template "chart.description" . }}
 {{ template "chart.homepageLine" . }}
 
-The Application Observability feature enables the collection of application telemetry data. Enabling this feature
-requires enabling one or more receivers where data will be sent from the application.
+The Application Observability feature enables the collection of application telemetry data. 
+
+## Before enabling
+
+Before you enable this feature, you must enable one or more receivers where data will be sent from the application.
 
 ## Testing
 
-This chart contains unit tests to verify the generated configuration. A hidden value, `deployAsConfigMap`, will render
-the generated configuration into a ConfigMap object. This ConfigMap is not used during regular operation, but it is
-useful for showing the outcome of a given values file.
+This chart contains unit tests to verify the generated configuration. The hidden value `deployAsConfigMap` will render
+the generated configuration into a ConfigMap object. While this ConfigMap is not used during regular operation, you can use
+it to show the outcome of a given values file.
 
-The unit tests use this to create an object with the configuration that can be asserted against. To run the tests, use
+The unit tests use this ConfigMap to create an object with the configuration that can be asserted against. To run the tests, use
 `helm test`.
 
-Actual integration testing in a live environment should be done in the main [k8s-monitoring](../k8s-monitoring) chart.
+Be sure perform actual integration testing in a live environment in the main [k8s-monitoring](../k8s-monitoring) chart.
 
 {{ template "chart.maintainersSection" . }}
 <!-- markdownlint-disable no-bare-urls -->

diff --git a/charts/feature-auto-instrumentation/README.md b/charts/feature-auto-instrumentation/README.md
@@ -8,19 +8,15 @@
 ![Version: 1.0.0](https://img.shields.io/badge/Version-1.0.0-informational?style=flat-square) ![AppVersion: 1.0.0](https://img.shields.io/badge/AppVersion-1.0.0-informational?style=flat-square)
 Gathers telemetry data via automatic instrumentation
 
-The auto-instrumentation feature deploys Grafana Beyla to automatically instrument programs running on this cluster
-using eBPF.
+The auto-instrumentation feature deploys Grafana Beyla to automatically instrument programs running on this cluster using eBPF.
 
 ## Testing
 
-This chart contains unit tests to verify the generated configuration. A hidden value, `deployAsConfigMap`, will render
-the generated configuration into a ConfigMap object. This ConfigMap is not used during regular operation, but it is
-useful for showing the outcome of a given values file.
+This chart contains unit tests to verify the generated configuration. The hidden value `deployAsConfigMap` will render the generated configuration into a ConfigMap object. While this ConfigMap is not used during regular operation, you can use it to show the outcome of a given values file.
 
-The unit tests use this to create an object with the configuration that can be asserted against. To run the tests, use
-`helm test`.
+The unit tests use this ConfigMap to create an object with the configuration that can be asserted against. To run the tests, use `helm test`.
 
-Actual integration testing in a live environment should be done in the main [k8s-monitoring](../k8s-monitoring) chart.
+Be sure perform actual integration testing in a live environment in the main [k8s-monitoring](../k8s-monitoring) chart.
 
 ## Maintainers
 

diff --git a/charts/feature-auto-instrumentation/README.md.gotmpl b/charts/feature-auto-instrumentation/README.md.gotmpl
@@ -9,19 +9,15 @@
 {{ template "chart.description" . }}
 {{ template "chart.homepageLine" . }}
 
-The auto-instrumentation feature deploys Grafana Beyla to automatically instrument programs running on this cluster
-using eBPF.
+The auto-instrumentation feature deploys Grafana Beyla to automatically instrument programs running on this cluster using eBPF.
 
 ## Testing
 
-This chart contains unit tests to verify the generated configuration. A hidden value, `deployAsConfigMap`, will render
-the generated configuration into a ConfigMap object. This ConfigMap is not used during regular operation, but it is
-useful for showing the outcome of a given values file.
+This chart contains unit tests to verify the generated configuration. The hidden value `deployAsConfigMap` will render the generated configuration into a ConfigMap object. While this ConfigMap is not used during regular operation, you can use it to show the outcome of a given values file.
 
-The unit tests use this to create an object with the configuration that can be asserted against. To run the tests, use
-`helm test`.
+The unit tests use this ConfigMap to create an object with the configuration that can be asserted against. To run the tests, use `helm test`.
 
-Actual integration testing in a live environment should be done in the main [k8s-monitoring](../k8s-monitoring) chart.
+Be sure perform actual integration testing in a live environment in the main [k8s-monitoring](../k8s-monitoring) chart.
 
 {{ template "chart.maintainersSection" . }}
 <!-- markdownlint-disable no-bare-urls -->

diff --git a/charts/feature-cluster-events/README.md b/charts/feature-cluster-events/README.md
@@ -8,19 +8,22 @@
 ![Version: 1.0.0](https://img.shields.io/badge/Version-1.0.0-informational?style=flat-square) ![AppVersion: 1.0.0](https://img.shields.io/badge/AppVersion-1.0.0-informational?style=flat-square)
 Gathers Kubernetes Events
 
-The Cluster Events feature enables the collection of Kubernetes events from the cluster. Events are captured as logs and
-are annotated with additional metadata to make them easier to search and filter.
+The Cluster Events feature enables the collection of Kubernetes events from the cluster.
+
+## How it works
+
+Events are captured as logs and are annotated with additional metadata to make them easier to search and filter.
 
 ## Testing
 
-This chart contains unit tests to verify the generated configuration. A hidden value, `deployAsConfigMap`, will render
-the generated configuration into a ConfigMap object. This ConfigMap is not used during regular operation, but it is
-useful for showing the outcome of a given values file.
+This chart contains unit tests to verify the generated configuration. The hidden value `deployAsConfigMap` will render
+the generated configuration into a ConfigMap object. While this ConfigMap is not used during regular operation, you can use
+it to show the outcome of a given values file.
 
-The unit tests use this to create an object with the configuration that can be asserted against. To run the tests, use
+The unit tests use this ConfigMap to create an object with the configuration that can be asserted against. To run the tests, use
 `helm test`.
 
-Actual integration testing in a live environment should be done in the main [k8s-monitoring](../k8s-monitoring) chart.
+Be sure perform actual integration testing in a live environment in the main [k8s-monitoring](../k8s-monitoring) chart.
 
 ## Maintainers
 

diff --git a/charts/feature-cluster-events/README.md.gotmpl b/charts/feature-cluster-events/README.md.gotmpl
@@ -9,19 +9,22 @@
 {{ template "chart.description" . }}
 {{ template "chart.homepageLine" . }}
 
-The Cluster Events feature enables the collection of Kubernetes events from the cluster. Events are captured as logs and
-are annotated with additional metadata to make them easier to search and filter.
+The Cluster Events feature enables the collection of Kubernetes events from the cluster. 
+
+## How it works
+
+Events are captured as logs and are annotated with additional metadata to make them easier to search and filter.
 
 ## Testing
 
-This chart contains unit tests to verify the generated configuration. A hidden value, `deployAsConfigMap`, will render
-the generated configuration into a ConfigMap object. This ConfigMap is not used during regular operation, but it is
-useful for showing the outcome of a given values file.
+This chart contains unit tests to verify the generated configuration. The hidden value `deployAsConfigMap` will render
+the generated configuration into a ConfigMap object. While this ConfigMap is not used during regular operation, you can use
+it to show the outcome of a given values file.
 
-The unit tests use this to create an object with the configuration that can be asserted against. To run the tests, use
+The unit tests use this ConfigMap to create an object with the configuration that can be asserted against. To run the tests, use
 `helm test`.
 
-Actual integration testing in a live environment should be done in the main [k8s-monitoring](../k8s-monitoring) chart.
+Be sure perform actual integration testing in a live environment in the main [k8s-monitoring](../k8s-monitoring) chart.
 
 {{ template "chart.maintainersSection" . }}
 <!-- markdownlint-disable no-bare-urls -->