Skip to content

Improve Synthetics notifications page structure and clarity#34782

Merged
git-thuerk-done merged 2 commits intomasterfrom
alicia.scott/synthetics-notification-presets-table
Feb 23, 2026
Merged

Improve Synthetics notifications page structure and clarity#34782
git-thuerk-done merged 2 commits intomasterfrom
alicia.scott/synthetics-notification-presets-table

Conversation

@git-thuerk-done
Copy link
Copy Markdown
Contributor

@git-thuerk-done git-thuerk-done commented Feb 23, 2026

What does this PR do? What is the motivation?

[From Docs AI day]

  • Rewrites the Synthetics notifications page to improve clarity and task orientation for first-time readers.

Changes:

  • Overview: Removes the flat feature list, and instead adds a Next steps section
  • Pre-filled monitor messages: Clarifies that defaults require no setup; wraps the five advanced Handlebars tab examples in a collapsible section so they don't overwhelm new readers (Also changed tab headings to organize by Test type as once I have the cdocs pages for the Template variables it will follow the same structure)
  • Notification presets: Rewrites the table with "What it shows" and "When to use it" columns; removes redundant intro copy; drops the vague channel comparison table
  • Display custom notifications: Removes duplicate intro copy that conflicted with the presets intro
  • Further reading: Replaces entries now covered by the new Next steps section with more useful links (monitor downtimes, alerting guide, monitor notifications)
  • Next steps: Adds a dedicated section linking to template variables, conditional alerting, advanced notifications, and the alerting guide

Merge instructions

Merge readiness:

  • Ready for merge

Additional notes

@git-thuerk-done git-thuerk-done requested a review from a team as a code owner February 23, 2026 20:13
@github-actions
Copy link
Copy Markdown
Contributor

Preview links (active after the build_preview check completes)

Modified Files

Comment thread content/en/synthetics/notifications/_index.md Outdated
Comment thread content/en/synthetics/notifications/_index.md Outdated
| `hide_all` | Hides all additional content except for the custom message and event link. |
Datadog adds enriched content to notifications by default—test metadata, screenshots, failing step details, and notification handles. Use presets to control which content appears:

<table style="table-layout: fixed;">
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Curious why you converted the Markdown table to be HTML? We should prefer Markdown tables unless there is a good reason not to use them.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was word wrapping the "preset" column with Markdown for some reason

Comment on lines +175 to 177
## Display custom notifications message

### Notification presets
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The old introductory paragraph for the "Display custom notifications" section was removed, so now this ## section jumps straight into the ### with no context. Consider either:

  • Adding a one-line intro under "Display custom notifications message", or
  • Promoting "Notification presets" to ## and removing the now-empty parent heading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good catch, this was certainly a claude thing that I should have noticed it was minimizing too much information!

Comment thread content/en/synthetics/notifications/_index.md Outdated
</tr>
<tr>
<td style="width: 120px;"><code>hide_handles</code></td>
<td>All enriched data, but no <code>@notification</code> handles (for example, <code>@slack-channel</code>)</td>
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this section saying that it will NOT show the @slack-channel channel? If yes, I'd recommend clarifying this in the example.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For this table, let me know if this keeps the meaning:

Preset What it shows Best for
show_all (default) All enriched data, metadata, and handles Email and ticketing channels where full context is useful
hide_handles All enriched data, but no handles (for example, @slack-channel) Channels already notified at the monitor level to prevent duplicate alerts
hide_all Custom message and event link only Chat channels where you control the full message format

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes I will make that more clear

Copy link
Copy Markdown
Contributor

@iadjivon iadjivon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @git-thuerk-done , thanks for this PR! I've added some comments, let me know if you have any questions.

@git-thuerk-done git-thuerk-done merged commit 3a00872 into master Feb 23, 2026
25 checks passed
@git-thuerk-done git-thuerk-done deleted the alicia.scott/synthetics-notification-presets-table branch February 23, 2026 22:07
GLorenzo679 pushed a commit that referenced this pull request Feb 24, 2026
* Improve Synthetics notifications page structure and clarity

* Update Synthetics notifications overview and preset descriptions
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants