From a89e333569f919eb0248878561f77ff592eee46e Mon Sep 17 00:00:00 2001
From: "grafana-delivery-bot[bot]"
 <132647405+grafana-delivery-bot[bot]@users.noreply.github.com>
Date: Wed, 22 May 2024 09:57:41 -0400
Subject: [PATCH] [v11.0.x] docs: update alert list visualization (#88175)

docs: update alert list visualization (#87815)

* docs: update alert list visualization

* Apply suggestions from code review

Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com>

* fix: linting errors

* docs: add youtube video

---------

Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com>
(cherry picked from commit 285567573e587360e3e6009029f80a26c1bc3d24)

Co-authored-by: Marie Cruz <mdcruz@users.noreply.github.com>
---
 .../visualizations/alert-list/index.md        | 77 +++++++++++++------
 1 file changed, 54 insertions(+), 23 deletions(-)

diff --git a/docs/sources/panels-visualizations/visualizations/alert-list/index.md b/docs/sources/panels-visualizations/visualizations/alert-list/index.md
index daf630f49fc..d4b39c2fc50 100644
--- a/docs/sources/panels-visualizations/visualizations/alert-list/index.md
+++ b/docs/sources/panels-visualizations/visualizations/alert-list/index.md
@@ -26,11 +26,17 @@ refs:
 
 # Alert list
 
-Use alert lists to display your alerts. You can configure the list to show the current state. You can read more about alerts in [Grafana Alerting overview](ref:grafana-alerting-overview).
+Alert lists allow you to display a list of important alerts that you want to track. You can configure the alert list to show the current state of your alert, such as firing, pending, or normal. Learn more about alerts in [Grafana Alerting overview][].
 
 {{< figure src="/static/img/docs/alert-list-panel/alert-list-panel.png" max-width="850px" alt="An alert list visualization" >}}
 
-Customize your visualization using the following settings.
+On each dashboard load, this visualization queries the alert list, always providing the most up-to-date results.
+
+## Configure an alert list
+
+Once you’ve created a [dashboard](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/), the following video shows you how to configure an alert list visualization:
+
+{{< youtube id="o4rK7_AXZ9Y" >}}
 
 ## Panel options
 
@@ -38,33 +44,58 @@ Customize your visualization using the following settings.
 
 ## Options
 
-- **Group mode -** Choose between "Default grouping" to show alert instances grouped by their alert rule, or "Custom grouping" to group alert instances by a custom set of labels.
-- **Max Items -** Sets the maximum number of alerts to list.
-- **Sort order -** Select how to order the alerts displayed:
-  - **Alphabetical (asc) -** Alphabetical order.
-  - **Alphabetical (desc) -** Reverse alphabetical order.
-  - **Importance -** By importance according to the following values, with 1 being the highest:
-    - alerting: 1
-    - firing: 1
-    - no_data: 2
-    - pending: 3
-    - ok: 4
-    - paused: 5
-    - inactive: 5
-  - **Time (asc) -** Newest active alert instances first.
-  - **Time (desc) -** Oldest active alert instances first.
-- **Alerts from this dashboard -** Shows alerts only from the dashboard the alert list is in.
+Use the following options to refine your alert list visualization.
+
+### Group mode
+
+Choose between **Default grouping** to show alert instances grouped by their alert rule, or **Custom grouping** to show alert instances grouped by a custom set of labels.
+
+### Max items
+
+Sets the maximum number of alerts to list. By default, Grafana sets this value to 10.
+
+### Sort order
+
+Select how to order the alerts displayed. Choose from:
+
+- **Alphabetical (asc) -** Alphabetical order.
+- **Alphabetical (desc) -** Reverse alphabetical order.
+- **Importance -** By importance according to the following values, with 1 being the highest:
+  - alerting: 1
+  - firing: 1
+  - no_data: 2
+  - pending: 3
+  - ok: 4
+  - paused: 5
+  - inactive: 5
+- **Time (asc) -** Newest active alert instances first.
+- **Time (desc) -** Oldest active alert instances first.
+
+### Alerts linked to this dashboard
+
+Toggle the switch on to only show alerts from the dashboard the alert list is in.
 
 ## Filter
 
 These options allow you to limit alerts shown to only those that match the query, folder, or tags you choose.
 
-- **Alert name -** Enter an alert name query.
-- **Alert instance label -** Filter alert instances using label querying, ex: `{severity="critical", instance=~"cluster-us-.+"}`.
-- **Folder -** Select a folder. Only alerts from dashboards in the folder selected will be displayed.
-- **Datasource -** Filter alerts from the selected data source.
+### Alert name
 
-## State filter
+Filter alerts by name.
+
+### Alert instance label
+
+Filter alert instances using [label](https://grafana.com/docs/grafana/latest/alerting/fundamentals/alert-rules/annotation-label/) querying. For example,`{severity="critical", instance=~"cluster-us-.+"}`.
+
+### Datasource
+
+Filter alerts from the selected data source.
+
+### Folder
+
+Filter alerts by the selected folder. Only alerts from dashboards in this folder are displayed.
+
+## Alert state filter
 
 Choose which alert states to display in this visualization.