From 569c85dab6cdee9e2e798b8652dcd0fc28d66f55 Mon Sep 17 00:00:00 2001
From: Vadim Stepanov <vadimkerr@gmail.com>
Date: Wed, 19 Apr 2023 16:11:22 +0100
Subject: [PATCH] Schedule quality docs (#1781)

# What this PR does
Add docs for schedule quality report feature.

## Which issue(s) this PR fixes
https://github.com/grafana/oncall/issues/1552

## 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] `CHANGELOG.md` updated (or `pr:no changelog` PR label added if not
required)
---
 .../calendar-schedules/web-schedule/_index.md | 32 +++++++++++++++++++
 .../apps/schedules/models/on_call_schedule.py |  6 +++-
 .../ScheduleQualityDetails.tsx                | 10 +++++-
 3 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/docs/sources/calendar-schedules/web-schedule/_index.md b/docs/sources/calendar-schedules/web-schedule/_index.md
index 4073aa0a..0f5500e3 100644
--- a/docs/sources/calendar-schedules/web-schedule/_index.md
+++ b/docs/sources/calendar-schedules/web-schedule/_index.md
@@ -51,6 +51,38 @@ Understand your schedule view:
 - **Overrides:** The override calendar represents temporary adjustments to the recurring on-call schedule. Any events
 on this calendar will take precedence over the rotations calendar.
 
+## Schedule quality report
+
+The schedule view features a quality report that provides a score for your schedule based on rotations and overrides.
+It's calculated based on these key factors:
+
+- Gaps (amount of time when no one is on-call)
+- Balance (uneven distribution of on-call shifts between team members)
+
+Quality score is a numeric value between 0 and 100. The higher the score, the better the schedule quality.
+Web UI uses the following scale to show the quality score:
+
+- 0-20: Bad
+- 20-40: Low
+- 40-60: Medium
+- 60-80: Good
+- 80-100: Great
+
+To improve quality score:
+
+- Minimize the amount of time when no one is on-call.
+- Ensure users in the schedule have a similar amount of on-call time.
+
+Depending on the quality score, the report can also provide:
+
+- Percentage of time when no one is on-call. E.g. "29% not covered" means that 29% of the time no one is on-call for
+the schedule. 24/7/365 coverage is considered ideal, so reducing this number will improve the overall schedule quality.
+- List of overloaded users. A user is considered overloaded if they have more on-call time than average for the schedule.
+E.g. "+15% avg" in quality report means that user has 15% more on-call time than average for the schedule.
+A perfectly balanced schedule is considered ideal, so reducing this number will improve the overall schedule quality.
+
+>**Note**: The next 52 weeks (~1 year) are taken into account when generating the quality report.
+
 ## Schedule export
 
 Export on-call schedules from Grafana OnCall to your preferred calendar app with a one-time secret iCal URL. The
diff --git a/engine/apps/schedules/models/on_call_schedule.py b/engine/apps/schedules/models/on_call_schedule.py
index c631c8d7..32f3cc03 100644
--- a/engine/apps/schedules/models/on_call_schedule.py
+++ b/engine/apps/schedules/models/on_call_schedule.py
@@ -467,7 +467,11 @@ class OnCallSchedule(PolymorphicModel):
             overloaded_users = []
         else:
             average_duration = timedelta_sum(duration_map.values()) / len(duration_map)
-            overloaded_user_pks = [user_pk for user_pk, duration in duration_map.items() if duration > average_duration]
+            overloaded_user_pks = [
+                user_pk
+                for user_pk, duration in duration_map.items()
+                if score_to_percent(duration / average_duration) > 100
+            ]
             usernames = {
                 u.public_primary_key: u.username
                 for u in User.objects.filter(public_primary_key__in=overloaded_user_pks).only(
diff --git a/grafana-plugin/src/components/ScheduleQualityDetails/ScheduleQualityDetails.tsx b/grafana-plugin/src/components/ScheduleQualityDetails/ScheduleQualityDetails.tsx
index b2fa2775..acb21a5c 100644
--- a/grafana-plugin/src/components/ScheduleQualityDetails/ScheduleQualityDetails.tsx
+++ b/grafana-plugin/src/components/ScheduleQualityDetails/ScheduleQualityDetails.tsx
@@ -110,7 +110,15 @@ export const ScheduleQualityDetails: FC<ScheduleQualityDetailsProps> = ({ qualit
           </HorizontalGroup>
           {expanded && (
             <Text type="primary" className={cx('text')}>
-              The next 52 weeks are taken into consideration when calculating the overall schedule quality.
+              The next 52 weeks (~1 year) are taken into account when generating the quality report. Refer to the{' '}
+              <a
+                href={'https://grafana.com/docs/oncall/latest/calendar-schedules/web-schedule/#schedule-quality-report'}
+                target="_blank"
+                rel="noreferrer"
+              >
+                documentation
+              </a>{' '}
+              for more details.
             </Text>
           )}
         </div>