From 155437f7b4ecfe6f1c6e766049875987f2412cf9 Mon Sep 17 00:00:00 2001
From: Eva Parish <eva.parish@datadoghq.com>
Date: Wed, 15 Oct 2025 14:05:13 -0400
Subject: [PATCH 1/3] Add annotations documentation

---
 config/_default/menus/main.en.yaml          |  5 +++
 content/en/dashboards/annotations/_index.md | 41 +++++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 content/en/dashboards/annotations/_index.md

diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml
index 89ba8ea3face3..2c1e07c0f5b2d 100644
--- a/config/_default/menus/main.en.yaml
+++ b/config/_default/menus/main.en.yaml
@@ -1619,6 +1619,11 @@ menu:
       parent: dashboards
       weight: 9
       identifier: dashboards_overlays
+    # - name: Annotations
+    #   url: dashboards/annotations/
+    #   parent: dashboards
+    #   weight: 901
+    #   identifier: dashboards_annotations
     - name: Sharing
       identifier: dashboards_sharing
       url: dashboards/sharing/
diff --git a/content/en/dashboards/annotations/_index.md b/content/en/dashboards/annotations/_index.md
new file mode 100644
index 0000000000000..134ccdfb65cd9
--- /dev/null
+++ b/content/en/dashboards/annotations/_index.md
@@ -0,0 +1,41 @@
+---
+title: Annotations
+description: Learn how to add, customize, and manage annotations on timeseries widgets in dashboards and notebooks to highlight important events.
+disable_toc: false
+---
+
+## Overview
+
+Annotations let you manually place vertical markers with descriptions on timeseries widgets. Adding annotations can be useful to visually call out key events like deploys, incidents, or spikes. Click any point in time and add a note.
+
+Annotations are available in both dashboards and notebooks. If you export a widget from a dashboard to a notebook, any annotations you've added to the widget persist.
+
+<!-- screenshot -->
+
+## Adding an annotation
+
+1. Create an annotation by:
+    - Left-clicking anywhere on a timeseries widget and selecting **Add annotation** from the context menu that appears, or
+    - Clicking the X axis on a timeseries
+3. Type your comment, and optionally click the timestamp field to manually adjust to the precise time you want to annotate.
+4. Optionally change the color of the annotation from the dropdown in the bottom left.
+5. Click **Save**.
+
+## Adding multiple annotations
+
+To apply an annotation to multiple timeseries at once:
+
+1. Select the widgets you want to apply the annotation to (or leave everything unselected to apply to all widgets).
+2. Follow steps 1–4 [above](#adding-an-annotation) to start creating an annotation.
+3. From the **Applying to** dropdown, choose **All widgets** or **Selected widgets**.
+4. Click **Save**.
+
+## Editing an annotation
+
+To edit an annotation you've created, hover over the annotation line, click the three dots menu, and choose **Edit** or **Edit for all widgets**.
+
+<div class="alert alert-info">You can't .</a></div>
+
+## Deleting an annotation
+
+To delete an annotation you've created, hover over the annotation line, click the three dots menu, and choose **Delete** or **Delete from all widgets**.
\ No newline at end of file

From 44a1a2403db7c5b37fcc30db800d5dd2bdd90a67 Mon Sep 17 00:00:00 2001
From: Eva Parish <eva.parish@datadoghq.com>
Date: Fri, 24 Oct 2025 14:16:51 -0400
Subject: [PATCH 2/3] Uncomment menu

---
 config/_default/menus/main.en.yaml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml
index 2c1e07c0f5b2d..19737e052b7dd 100644
--- a/config/_default/menus/main.en.yaml
+++ b/config/_default/menus/main.en.yaml
@@ -1619,11 +1619,11 @@ menu:
       parent: dashboards
       weight: 9
       identifier: dashboards_overlays
-    # - name: Annotations
-    #   url: dashboards/annotations/
-    #   parent: dashboards
-    #   weight: 901
-    #   identifier: dashboards_annotations
+    - name: Annotations
+      url: dashboards/annotations/
+      parent: dashboards
+      weight: 901
+      identifier: dashboards_annotations
     - name: Sharing
       identifier: dashboards_sharing
       url: dashboards/sharing/

From 5f793064b1272cfc40153e777d02d40004d4185e Mon Sep 17 00:00:00 2001
From: Eva Parish <eva.parish@datadoghq.com>
Date: Fri, 24 Oct 2025 14:20:00 -0400
Subject: [PATCH 3/3] Remove stray note

---
 content/en/dashboards/annotations/_index.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/content/en/dashboards/annotations/_index.md b/content/en/dashboards/annotations/_index.md
index 134ccdfb65cd9..00a1b7d13da63 100644
--- a/content/en/dashboards/annotations/_index.md
+++ b/content/en/dashboards/annotations/_index.md
@@ -34,8 +34,6 @@ To apply an annotation to multiple timeseries at once:
 
 To edit an annotation you've created, hover over the annotation line, click the three dots menu, and choose **Edit** or **Edit for all widgets**.
 
-<div class="alert alert-info">You can't .</a></div>
-
 ## Deleting an annotation
 
 To delete an annotation you've created, hover over the annotation line, click the three dots menu, and choose **Delete** or **Delete from all widgets**.
\ No newline at end of file