Add information about pages in incidents (#30837)

* Add information about pages in incidents

* Small fixes

* Apply suggestions from code review

Co-authored-by: Chris Kirk <[email protected]>

* Apply suggestions from code review

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

---------

Co-authored-by: Chris Kirk <[email protected]>
Co-authored-by: domalessi <[email protected]>

Author: 3 people

content/en/service_management/incident_management/declare.md

@@ -15,7 +15,7 @@ You can declare an incident from multiple places within the Datadog platform, su
 
 In the [Datadog UI][1], click **Declare Incident** to create an incident.
 
-The *Declare Incident* modal displays a collapsible side panel that contains helper text and descriptions for the severities and statuses used by your organization. The helper text and descriptions are customizable in [Incident Settings][2]. 
+The *Declare Incident* modal displays a collapsible side panel that contains helper text and descriptions for the severities and statuses used by your organization. The helper text and descriptions are customizable in [Incident Settings][2].
 
 ## From a monitor
 
@@ -32,7 +32,7 @@ Incidents created from a monitor will inherit [field values][10] from the monito
 Declare an incident directly from a Cloud SIEM or Workload Protection signal side panel, by clicking **Declare incident** or **Escalate Investigation**. For more information, see [Investigate Security Signals][3].
 
 Declare an incident from an App and API Protection signal through the actions listed in the signal side panel. Click **Show all actions** and click **Declare Incident**.
-For more information, see [Investigate Security Signals][4] for App and API Protection. 
+For more information, see [Investigate Security Signals][4] for App and API Protection.
 
 {{< img src="/service_management/incidents/declare/declare_asm.png" alt="Your image description" style="width:90%;" >}}
 
@@ -58,6 +58,10 @@ Use the [Datadog Clipboard][6] to gather multiple monitors and graphs and to gen
 
 {{< img src="service_management/incidents/declare/declare_clipboard.png" alt="Declare an incident from the Datadog Clipboard" style="width:90%;" >}}
 
+## From a Datadog On-Call page
+
+You can declare an incident directly from a [Datadog On-Call page][12]. From the [On-Call pages list][13], select a page and click **Declare Incident** to create an incident and automatically associate it with the relevant on-call team.
+
 ## From Slack
 
 If you have the [Datadog integration enabled on Slack][7], you can declare a new incident with the slash command `/datadog incident` from any Slack channel.
@@ -100,3 +104,5 @@ You can declare an incident from individual Handoff Notification cards.
 [9]: https://app.datadoghq.com/incidents/settings?section=global-settings
 [10]: /service_management/incident_management/incident_settings/property_fields
 [11]: /service_management/incident_management/incident_settings/notification_rules
+[12]: /service_management/on-call/
+[13]: https://app.datadoghq.com/on-call/pages

content/en/service_management/incident_management/incident_settings/notification_rules.md

@@ -19,8 +19,12 @@ Use notification rules to:
 
 1. Navigate to [Incident Settings Notification Rules][1].
 1. Click **New Rule**.
-2. Under **For incidents matching...**, select the incident property field `key:value` pairs you want notifications to be sent for. By default, these filters are empty, and a notification rule triggers for any incident.
-3. **Notify**: Select your notification recipients. Notifications can be sent to any of Datadog's existing [notification integrations][2]. If you want to notify a recipient's mobile device, select the option for their name that includes **(Mobile Push Notification)**. The recipient must have enabled notifications in the [Datadog mobile app][3] for this option to appear.
+1. Select the `key:value` pairs for the incident properties that should trigger a notification. By default, no filters are set, and a notification rule triggers whenever an incident is declared or its attributes are updated.
+1. Select your notification recipients.
+    - Send notifications to any of Datadog's [supported notification integrations][2].
+    - Notify [Datadog On-Call teams][4] using `@oncall-` handles.
+    - To notify a recipient's mobile device, find their name and select the option that includes **(Mobile Push Notification)**. The recipient must have notifications enabled in the [Datadog mobile app][3] for this option to appear.
+    - If you want to notify the incident Slack channel, use handle `@incident-slack-channel`.
 4. **With Template**: Select the desired message template you want the notification rule to use.
 5. **Renotify on updates to**: Select the incident properties that trigger notifications. A new notification is sent whenever one or more of the selected properties change. **Note**: properties already in your filters (see step 2) are automatically included in these rules.
 6. Click **Save**
@@ -39,3 +43,4 @@ You can perform the following operations to manage your notification rules.
 [1]: https://app.datadoghq.com/incidents/settings#Rules
 [2]: /monitors/notifications/?tab=is_alert#configure-notifications-and-automations
 [3]: /mobile/
+[4]: /service_management/on-call/

content/en/service_management/incident_management/notification.md

@@ -11,7 +11,14 @@ further_reading:
 
 ## Overview
 
-All stakeholder notifications for an incident are consolidated in the incident’s Notifications tab. You can manually create, save as draft, and send notifications directly from this page. Automated notifications sent by [Notification Rules][1] for the incident in question are also listed in this section.
+
+Effective incident response depends on notifying the right people at the right time. Datadog Incident Management provides two key ways to coordinate communication during an incident:
+
+- The **Notifications** tab centralizes stakeholder communications. From here, you can create and send manual updates, save drafts, and view all automated messages triggered by [Notification Rules][1].
+
+- The **Pages** tab helps you manage your on-call pages. From this tab, you can page [Datadog On-Call][4] teams to prompt them to join the incident response. This tab also shows a history of all pages sent, whether manually or through [Notification Rules][1], so that you can track which teams have been paged and when.
+
+These tools ensure that both stakeholders and technical responders are promptly and reliably informed throughout the incident lifecycle.
 
 ## Add a notification
 
@@ -25,13 +32,22 @@ To create a manual notification:
 1. Use the `{{incident.created}}` variable to customize your message timezone. This template variable will display the option to set your variable time zone.
 1. Send your notification or save it as a draft.
 
+## Trigger a page from an incident
+
+To page a team or user using [Datadog On-Call][4]:
+1. Navigate to the **Pages** tab of an incident.
+1. Click **Page**.
+1. Select the team or user you want to alert.
+1. (Optional) Assign an incident role automatically to the person who acknowledges the page.
+1. Click **Page**.
+
 ## View all notifications
 
 {{< img src="/service_management/incidents/notification/incident_notifications_sent.png" alt="Notification tab of an incident showing example list of sent messages" style="width:90%;" >}}
 
 The Notifications tab of an incident lists notifications as **Drafts** and **Sent**. Both lists display:
 - The (intended) recipients of a notification.
-- The contents of the notification’s message and any renotification messages that were sent.
+- The contents of the notification's message and any renotification messages that were sent.
 - When the notification was last updated.
 - The original author of the notification.
 
@@ -45,7 +61,7 @@ For more information on how to configure a new notification rule, see the [Incid
 
 ## Message templates
 
-Message templates are dynamic, reusable messages that can be used in [manual incident notifications](#add-a-notification), or automated [notification rules](#customize-notification-rules). Message templates leverage template variables, such as `{{incident.severity}}`, to dynamically inject the corresponding value from the incident that the notification is being sent for. Message templates have Markdown support so that incident notifications can include text formatting, tables, indented lists, and hyperlinks. Template variables are supported in both the message’s title and body.
+Message templates are dynamic, reusable messages that can be used in [manual incident notifications](#add-a-notification), or automated [notification rules](#customize-notification-rules). Message templates leverage template variables, such as `{{incident.severity}}`, to dynamically inject the corresponding value from the incident that the notification is being sent for. Message templates have Markdown support so that incident notifications can include text formatting, tables, indented lists, and hyperlinks. Template variables are supported in both the message's subject and body.
 
 For more information on how to create a message template, see the [Incident Settings][3] documentation.
 
@@ -56,3 +72,4 @@ For more information on how to create a message template, see the [Incident Sett
 [1]: /service_management/incident_management/incident_settings/notification_rules
 [2]: /monitors/notify/variables/?tab=is_alert
 [3]: /service_management/incident_management/incident_settings/templates
+[4]: /service_management/on-call/