From b4eb5f130441ef971d2cc941c75430c16ef1946b Mon Sep 17 00:00:00 2001
From: Pepe Cano <825430+ppcano@users.noreply.github.com>
Date: Thu, 13 Mar 2025 17:21:05 +0100
Subject: [PATCH] [release-11.5.3] docs(alerting): minor enhancements to intro
 concepts and example (#102068)

docs(alerting): minor enhancements to intro concepts and example (#102023)

* docs(alerting): minor enhancements to intro concepts and example

* Update docs/sources/alerting/fundamentals/alert-rules/annotation-label.md

Co-authored-by: Johnny Kartheiser <140559259+JohnnyK-Grafana@users.noreply.github.com>

---------

Co-authored-by: Johnny Kartheiser <140559259+JohnnyK-Grafana@users.noreply.github.com>
(cherry picked from commit 64b65ffc72c65bd595a12f5d1db17d84c04386e3)
---
 .../alerting-rules/templates/_index.md        |  2 +-
 .../alert-rules/annotation-label.md           |  2 ++
 .../alerting/fundamentals/templates.md        | 19 +++++++++----------
 3 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/docs/sources/alerting/alerting-rules/templates/_index.md b/docs/sources/alerting/alerting-rules/templates/_index.md
index f6da85e1977..cb12bf47513 100644
--- a/docs/sources/alerting/alerting-rules/templates/_index.md
+++ b/docs/sources/alerting/alerting-rules/templates/_index.md
@@ -176,7 +176,7 @@ Template labels when the labels returned by your queries are insufficient. For i
 
 Here’s an example of templating a `severity` label based on the query value.
 
-```
+```go
 {{ if (gt $values.A.Value 90.0) -}}
 critical
 {{ else if (gt $values.A.Value 80.0) -}}
diff --git a/docs/sources/alerting/fundamentals/alert-rules/annotation-label.md b/docs/sources/alerting/fundamentals/alert-rules/annotation-label.md
index 41d3c4c0220..ade6b016049 100644
--- a/docs/sources/alerting/fundamentals/alert-rules/annotation-label.md
+++ b/docs/sources/alerting/fundamentals/alert-rules/annotation-label.md
@@ -136,6 +136,8 @@ If multiple label keys are sanitized to the same value, the duplicates have a sh
 
 Annotations add additional information to alert instances, helping responders identify and address potential issues.
 
+Create clear and self-explanatory annotations so that first responders can investigate without needing deeper knowledge of the alert setup.
+
 Annotations are displayed in Grafana and are included by default in notifications. Grafana provides several optional annotations that you can edit:
 
 - `summary`: A short summary of what the alert has detected and why.
diff --git a/docs/sources/alerting/fundamentals/templates.md b/docs/sources/alerting/fundamentals/templates.md
index 3b2fa4de8c5..4e4243aee9c 100644
--- a/docs/sources/alerting/fundamentals/templates.md
+++ b/docs/sources/alerting/fundamentals/templates.md
@@ -63,6 +63,7 @@ In Grafana, you have various options to template your alert notification message
 
    - Labels are used to differentiate an alert instance from all other alert instances.
    - Template labels to add an additional label based on a query value, or when the labels from the query are incomplete or not descriptive enough.
+   - Avoid displaying query values in labels as this can create numerous alert instances—use annotations instead.
 
 1. [Notification templates](#template-notifications)
    - Notification templates are used by contact points for consistent messaging in notification titles and descriptions.
@@ -124,18 +125,16 @@ You can also template labels based on query results. This is helpful if the labe
 - Add a new label to change how alerts are identified and grouped into different alert groups.
 - Add a new label used by notification policies or silences to manage how the alert is handled.
 
-Here’s an example of templating a `severity` label based on the query value:
+Here’s an example of templating a new `env` label based on the value of a query label:
 
 ```go
-{{ if (gt $values.A.Value 90.0) -}}
-critical
-{{ else if (gt $values.A.Value 80.0) -}}
-high
-{{ else if (gt $values.A.Value 60.0) -}}
-medium
-{{ else -}}
-low
-{{- end }}
+{{- if eq $labels.instance "prod-server-1" -}}
+production
+{{- else if eq $labels.instance "staging-server-1" -}}
+staging
+{{- else -}}
+development
+{{- end -}}
 ```
 
 For more details on how to template labels, refer to [Template annotations and labels](ref:templating-labels-annotations).