[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 64b65ffc72)

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) -}}

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.

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) -}}
+{{- if eq $labels.instance "prod-server-1" -}}
-critical
+production
-{{ else if (gt $values.A.Value 80.0) -}}
+{{- else if eq $labels.instance "staging-server-1" -}}
-high
+staging
-{{ else if (gt $values.A.Value 60.0) -}}
+{{- else -}}
-medium
+development
-{{ else -}}
+{{- end -}}
-low
-{{- end }}
 ```
 
 For more details on how to template labels, refer to [Template annotations and labels](ref:templating-labels-annotations).