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)

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

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(

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>