[Draft] Better documentation for notification preferences for On-Call (…

…#26907)

Co-authored-by: cswatt <[email protected]>

config/_default/menus/main.en.yaml

@@ -2285,6 +2285,11 @@ menu:
       parent: oncall
       identifier: oncall_profile_settings
       weight: 6
+    - name: Guides
+      url: service_management/on-call/guides/
+      parent: oncall
+      identifier: oncall_guides
+      weight: 7
     - name: Event Management
       url: service_management/events/
       pre: events

config/_default/menus/main.fr.yaml

@@ -2095,21 +2095,31 @@ menu:
       parent: oncall
       identifier: oncall_pages
       weight: 2
+    - name: Processing Rules
+      url: service_management/on-call/processing_rules/
+      parent: oncall
+      identifier: oncall_processing_rules
+      weight: 3
     - name: Escalation Policies
       url: service_management/on-call/escalation_policies/
       parent: oncall
       identifier: oncall_escalation_policies
-      weight: 3
+      weight: 4
     - name: Schedules
       url: service_management/on-call/schedules/
       parent: oncall
       identifier: oncall_schedules
-      weight: 4
+      weight: 5
     - name: Profile Settings
       url: service_management/on-call/profile_settings/
       parent: oncall
       identifier: oncall_profile_settings
-      weight: 5
+      weight: 6
+    - name: Guides
+      url: service_management/on-call/guides/
+      parent: oncall
+      identifier: oncall_guides
+      weight: 7
     - name: Event Management
       url: service_management/events/
       pre: events

config/_default/menus/main.ja.yaml

@@ -2095,21 +2095,31 @@ menu:
       parent: oncall
       identifier: oncall_pages
       weight: 2
+    - name: Processing Rules
+      url: service_management/on-call/processing_rules/
+      parent: oncall
+      identifier: oncall_processing_rules
+      weight: 3
     - name: Escalation Policies
       url: service_management/on-call/escalation_policies/
       parent: oncall
       identifier: oncall_escalation_policies
-      weight: 3
+      weight: 4
     - name: Schedules
       url: service_management/on-call/schedules/
       parent: oncall
       identifier: oncall_schedules
-      weight: 4
+      weight: 5
     - name: Profile Settings
       url: service_management/on-call/profile_settings/
       parent: oncall
       identifier: oncall_profile_settings
-      weight: 5
+      weight: 6
+    - name: Guides
+      url: service_management/on-call/guides/
+      parent: oncall
+      identifier: oncall_guides
+      weight: 7
     - name: Event Management
       url: service_management/events/
       pre: events

config/_default/menus/main.ko.yaml

@@ -2095,21 +2095,31 @@ menu:
       parent: oncall
       identifier: oncall_pages
       weight: 2
+    - name: Processing Rules
+      url: service_management/on-call/processing_rules/
+      parent: oncall
+      identifier: oncall_processing_rules
+      weight: 3
     - name: Escalation Policies
       url: service_management/on-call/escalation_policies/
       parent: oncall
       identifier: oncall_escalation_policies
-      weight: 3
+      weight: 4
     - name: Schedules
       url: service_management/on-call/schedules/
       parent: oncall
       identifier: oncall_schedules
-      weight: 4
+      weight: 5
     - name: Profile Settings
       url: service_management/on-call/profile_settings/
       parent: oncall
       identifier: oncall_profile_settings
-      weight: 5
+      weight: 6
+    - name: Guides
+      url: service_management/on-call/guides/
+      parent: oncall
+      identifier: oncall_guides
+      weight: 7
     - name: 가이드 및 리소스
       url: service_management/events/
       pre: events

content/en/service_management/on-call/guides/_index.md

@@ -0,0 +1,9 @@
+---
+title: On-Call Guides
+private: false
+disable_toc: true
+---
+
+{{< whatsnext desc="General guides:">}}
+    {{< nextlink href="/service_management/on-call/guides/configure-mobile-device-for-on-call" >}}Set up your mobile device for Datadog On-Call{{< /nextlink >}}
+{{< /whatsnext >}}

content/en/service_management/on-call/guides/configure-mobile-device-for-on-call.md

@@ -0,0 +1,122 @@
+---
+title: Set Up Your Mobile Device for Datadog On-Call
+further_reading:
+- link: "https://docs.datadoghq.com/service_management/on-call/"
+  tag: "Documentation"
+  text: "On-Call Documentation"
+---
+
+Being on-call requires reliable and timely notifications to ensure you can respond to incidents effectively. This guide walks you through the steps to configure your mobile device for optimal performance with Datadog On-Call.
+
+1. Install the [Datadog mobile app][1].
+2. [Set up push notifications](#set-up-push-notifications): Enable your device to receive notifications from the Datadog mobile app.
+3. [Circumvent mute and Do Not Disturb mode](#circumvent-mute-and-do-not-disturb-mode): Receive push notifications, voice calls, and SMS while your device is in Do Not Disturb mode.
+
+## Set up push notifications
+<div class="alert alert-info">
+When you log into the Datadog mobile app for the first time, an onboarding flow takes care of notification settings and permissions.
+</div>
+
+By default, the mobile app is not allowed to send you notifications. To receive push notifications on On-Call events: 
+
+{{< tabs >}}
+{{% tab "iOS" %}}
+
+1. In the Datadog mobile app, navigate to **Account** > **Settings** > **Notifications**. 
+
+   {{< img src="service_management/oncall/app_settings_iOS.png" alt="Find the notification settings in the iOS version of Datadog's mobile app." style="width:35%;" >}}
+
+2. Enable the **Enable Notifications** toggle. If this is your first time enabling notifications, this opens up a permissions prompt. Grant permission, then touch **Enable Notifications** again to go to the iOS system settings. 
+
+   {{< img src="service_management/oncall/system_notifications_settings_iOS.png" alt="Configure the system notification settings of your iOS device." style="width:100%;" >}}
+
+3. Within the iOS system settings, make sure you enable the **Allow Notifications** toggle. Datadog highly recommends you also enable the **Sound** and **Badges** toggles.
+
+Make sure you grant the mobile app the necessary permissions.
+{{% /tab %}}
+
+{{% tab "Android" %}}
+1. In the Datadog mobile app, navigate to **Account** > **Settings** > **Notifications**. 
+
+   {{< img src="service_management/oncall/app_settings_android.png" alt="Find the notification settings in the Android version of Datadog's mobile app." style="width:35%;" >}}
+
+2. Tap **Notifications** to go to the system settings and configure your preferred app notifications. 
+
+   {{< img src="service_management/oncall/system_notifications_settings_android.png" alt="Configure the system notification settings of your Android device." style="width:100%;" >}}
+
+3. Within the Android system settings, enable the **Allow notifications** toggle. Datadog highly recommends you also select **Allow sound and vibration**.
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Custom sounds
+On both iOS and Android, you have the option to override the default system notification sounds. For high-urgency notifications, Datadog strongly recommends customizing your system sounds and volume settings. This ensures that alerts are not only more distinct and recognizable, but also more effective in capturing attention. The Datadog app comes preloaded with a selection of custom sounds.
+
+## Circumvent mute and Do Not Disturb mode
+You can override your device's system volume and Do Not Disturb mode for both push notifications (from the Datadog mobile app) and telephony notifications (such as voice call and SMS). 
+
+### Push notifications
+{{< tabs >}}
+{{% tab "iOS" %}}
+
+{{< img src="service_management/oncall/override_dnd_push_iOS.png" alt="Override your iOS device's system volume and do-not-disturb mode." style="width:100%;" >}}
+
+1. In the Datadog mobile app, navigate to **Account** > **Settings** > **Notifications**. 
+
+2. Enable the **Enable Critical Alerts** toggle.
+
+Critical alerts ignore the mute switch and Do Not Disturb. If you enable critical alerts, the system plays a critical alert’s sound regardless of the device’s mute or Do Not Disturb settings.
+
+Make sure you grant the mobile app the necessary permissions.
+
+{{% /tab %}}
+{{% tab "Android" %}}
+
+{{< img src="service_management/oncall/override_dnd_push_android.png" alt="Override your Android device's system volume and Do Not Disturb mode." style="width:100%;" >}}
+
+1. In the Datadog mobile app, navigate to **Account** > **Settings** > **Notifications**. 
+
+2. Enable the **Override system volume** toggle. This leads you to your system settings. Find the row for the Datadog mobile app and ensure that the toggle is enabled.
+
+<div class="alert alert-danger">
+On Android, the Datadog mobile app cannot bypass system volume or Do Not Disturb settings when used within a Work Profile. As a workaround, install the Datadog mobile app on your personal profile.
+</div>
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Telephony channels (voice calls and SMS)
+
+For reliability, Datadog uses a rotating set of phone numbers to contact you. To help your phone recognize calls and messages from Datadog On-Call, you can create a digital contact card. This card automatically updates with Datadog's latest phone numbers. You can assign special permissions to this contact in your system settings for enhanced functionality, such as circumventing Do Not Disturb mode.
+
+{{< tabs >}}
+{{% tab "iOS" %}}
+
+{{< img src="service_management/oncall/override_dnd_telephony_iOS.png" alt="Override your iOS device's Do Not Disturb mode for SMS and voice calls" style="width:100%;" >}}
+
+1. In the Datadog mobile app, navigate to **Account** > **Settings** > **Notifications**. 
+
+2. Toggle on **Enable Automatic Contact Card Sync**. This creates a contact named "Datadog On-Call", which updates regularly with Datadog's latest phone numbers.
+
+3. After this contact is created, open your iOS system settings and navigate to **Focus** > **Do Not Disturb**. 
+
+4. Under **People**, allow notifications from the Datadog On-Call contact. If you enabled critical alerts for Datadog push applications, then the Datadog mobile app also appears under **Apps**.
+{{% /tab %}}
+
+{{% tab "Android" %}}
+
+{{< img src="service_management/oncall/override_dnd_telephony_android.png" alt="Override your Android device's do-not-disturb mode for SMS and voice calls" style="width:100%;" >}}
+
+1. In the Datadog mobile app, navigate to **Account** > **Settings** > **Notifications**. 
+
+2. Under **Phone & SMS**, enable **Automatic Contact Card Sync**. This creates a contact named "Datadog On-Call", which updates regularly with Datadog's latest phone numbers.
+
+3. After this contact is created, mark it as a favorite.
+
+4. Open your Android system settings and navigate to **Sound & vibration** > **Do Not Disturb**. Create an exception for the Datadog On-Call contact.
+
+{{% /tab %}}
+{{< /tabs >}}
+
+
+[1]: /service_management/mobile/?tab=ios

content/en/service_management/on-call/profile_settings.md

@@ -6,6 +6,10 @@ further_reading:
   text: 'Datadog On-Call'
 ---
 
+<div class="alert alert-info">
+To use Datadog On-Call on your mobile device, install the <a href="/mobile#installing">Datadog mobile app</a>.
+</div>
+
 {{< site-region region="gov" >}}
 <div class="alert alert-warning">On-Call is not supported for your selected <a href="/getting_started/site">Datadog site</a> ({{< region-param key="dd_site_name" >}}).</div>
 {{< /site-region >}}
@@ -17,33 +21,53 @@ You must [configure your profile settings][1] before you can receive On-Call Pag
 Go to [My On-Call Profile][1] to configure your settings.
 
 ### Contact methods
-{{< img src="service_management/oncall/settings_contact.png" alt="Adding contact methods in On-Call profile settings. A phone number and an email are configured. The phone number is in a hover state, displaying 'Test Call' and 'Test SMS' options." style="width:100%;" >}}
-   - You must manually add your email or phone number.
+{{< img src="service_management/oncall/contact_methods.png" alt="Adding contact methods in On-Call profile settings. A phone number, an email, and a mobile device are configured. The phone number is in a hover state, displaying 'Test Call' and 'Test SMS' options." style="width:100%;" >}}
+   - You must manually add your email or phone number. Afterwards, the screen asks you for consent to reach you through SMS. If you consent, a green badge appears next to your phone number, indicating that it can be used for SMS notification preferences below.
    - If the Datadog [mobile app][2] is installed on your device, your device appears automatically in this list. Check your settings in the mobile app to ensure that your device can receive notifications.
    - Datadog recommends that you test each of your contact methods. Hover over your contact method for test options.
 
+#### Supported contact methods
+- Push notifications through the [Datadog mobile app][3]
+- Emails (HTML or text format)
+- SMS
+- Phone calls
+
+To set up your mobile device, including how to **circumvent Do Not Disturb mode**, see [Set Up Your Mobile Device for Datadog On-Call][4].
+
 ### Notification preferences
-{{< img src="service_management/oncall/settings_preferences.png" alt="Configuring notification preferences in On-Call profile settings. Two configurations: 'When a high urgency Page is triggered' set to notify a phone number immediately, and 'When a low urgency Page is triggered' set to notify an email after one minute." style="width:100%;" >}}
+Notification preferences allow you to tailor how and when **you** are alerted for On-Call Pages based on the urgency of the situation. By configuring preferences for low urgency and high urgency, you can ensure that notifications are effective and unobtrusive, depending on the urgency of the Page. The urgency of a Page is determined within your [Processing Rules][5].
+
+The system cycles through your configured notification preferences until you either acknowledge the Page, or the Page is escalated to the next on-call person as defined in the [Escalation Policy][6].
+
+#### High urgency notifications
+{{< img src="service_management/oncall/high_urgency_notification_preferences.png" alt="Configuring high urgency notification preferences in On-Call profile settings: 'When a high urgency Page is triggered' set to notify a phone number immediately in order to quickly respond to critical Pages." style="width:100%;" >}}
+
+Configure your high-urgency Pages (P1 monitor alerts, SEV-1 security threats, SEV-1 incidents, etc.), to demand immediate attention and escalation.
 
-Configure **Notification Preferences** to control when and how you receive On-Call related notifications, depending on the urgency of the Page.
+For example, you can configure On-Call to start with a push notification, call after one minute, and send a follow-up push notification if unacknowledged after two minutes.
+
+##### Best practices for high urgency
+- Use immediate push notifications and phone calls as the primary notification method for critical Pages.
+- Keep follow-up intervals short to ensure rapid acknowledgment.
+- Plan escalation policies carefully to avoid missed responses during emergencies.
+
+#### Low urgency notifications
+{{< img src="service_management/oncall/low_urgency_notification_preferences.png" alt="Configuring low urgency notification preferences in On-Call profile settings: 'When a low urgency Page is triggered' set to notify an email immediately but don't escalate it further." style="width:100%;" >}}
+
+Configure your low-urgency Pages (non-blocking issues, informational signals, etc.), to minimize disruptions while ensuring you stay informed. For example, you can opt to only yourself through email.
 
 ### Other notifications
 {{< img src="service_management/oncall/settings_shift_reminder.png" alt="Configuring a shift reminder in On-Call profile settings. A shift reminder is configured to notify a phone number 10 minutes before the shift begins." style="width:100%;" >}}
 
 Under **Other Notifications**, you can opt to receive a **Shift reminder** before your On-Call shift begins.
 
-### Supported notification methods
-
-Datadog supports:
-- Push notifications through the [Datadog mobile app][3]
-- Emails (HTML or text format)
-- SMS
-- Phone calls
-
 ## Further Reading
 
 {{< partial name="whats-next/whats-next.html" >}}
 
 [1]: https://app.datadoghq.com/on-call/profile
 [2]: /service_management/mobile/?tab=ios
 [3]: /mobile
+[4]: /service_management/on-call/guides/configure-mobile-device-for-on-call
+[5]: /service_management/on-call/processing_rules
+[6]: /service_management/on-call/escalation_policies