From 324b0c42868721712e7712288812006fc0e66556 Mon Sep 17 00:00:00 2001
From: Vadim Stepanov <vadimkerr@gmail.com>
Date: Thu, 11 Jul 2024 17:47:52 +0100
Subject: [PATCH] Make docs clearer for "Notify users one by one" policy
 (#4662)

# What this PR does

Clarifies how the `Notify users one by one (round robin)` escalation
policy works.

## Which issue(s) this PR closes

Related to https://github.com/grafana/support-escalations/issues/11449

<!--
*Note*: if you have more than one GitHub issue that this PR closes, be
sure to preface
each issue link with a [closing
keyword](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue).
This ensures that the issue(s) are auto-closed once the PR has been
merged.
-->

## Checklist

- [x] Unit, integration, and e2e (if applicable) tests updated
- [x] Documentation added (or `pr:no public docs` PR label added if not
required)
- [x] Added the relevant release notes label (see labels prefixed w/
`release:`). These labels dictate how your PR will
    show up in the autogenerated release notes.
---
 .../configure/escalation-chains-and-routes/index.md        | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/sources/configure/escalation-chains-and-routes/index.md b/docs/sources/configure/escalation-chains-and-routes/index.md
index 1b497b3a04..8f44e8fb5a 100644
--- a/docs/sources/configure/escalation-chains-and-routes/index.md
+++ b/docs/sources/configure/escalation-chains-and-routes/index.md
@@ -88,8 +88,11 @@ via the method configured in their user profile.
 * `Notify Slack User Group` - send a notification to each member of a slack user group. These users will be notified
 via the method configured in their user profile.
 * `Trigger outgoing webhook` - trigger an [outgoing webhook].
-* `Notify users one by one (round robin)` - each notification will be sent to a group of
-users one by one, in sequential order in [round robin fashion](https://en.wikipedia.org/wiki/Round-robin_item_allocation).
+* `Notify users one by one (round robin)` - notify users sequentially, cycling through users for **different alert groups**.
+Example: if users A, B, and C are in the list, the first alert group notifies A, the second alert group notifies B, and
+the third alert group notifies C. Note: users are sorted alphabetically by their username.
+To notify multiple users **within the same alert group** until someone acknowledges, instead use `Notify users` policies with
+`Wait` policies between them in the escalation chain.
 * `Continue escalation if current time is in range` - continue escalation only if current
 time is in specified range. It will wait for the specfied time to continue escalation.
 Useful when you want to get escalation only during working hours