docs: build alerts as code

[royendo]

I'm not sure what we should call the sidebar title, alerts seems overlapping with explore/alerts, granted theyll be separated soon into dev and user pages..

thoughts?

reason: there's been at least 2 questions related to data quality but customer was on live connector so good to shout out that they can use alerts instead

Checklist:

• Covered by tests
• Ran it and it works as intended
• Reviewed the diff before requesting a review
• Checked for unhandled edge cases
• Linked the issues it closes
• Checked if the docs need to be updated. If so, create a separate Linear DOCS issue
• Intend to cherry-pick into the release branch
• I'm proud of this work!

[ericpgreen2]

The documentation addresses a real user need and the live connector tip is valuable. However, each section needs 1-2 sentences of explanatory context before diving into YAML snippets. Currently the page reads as a series of code blocks without enough connective prose.

Sections needing additional context:

1. Metrics SQL (line 78): Add a sentence clarifying when to use metrics_sql vs regular sql. The metrics_sql syntax is documented in Custom APIs—consider linking there or adding a brief explanation.

2. Custom API (line 89): Add a sentence explaining when you'd use this approach. Link to Custom APIs.

3. Resource Status (line 101): Add use case context (e.g., "useful for monitoring pipeline health and catching reconciliation failures").

4. Recovery Notifications (line 156): Explain when you'd want each option. For example: "Use on_recover to confirm issues are resolved; use on_error to catch alert evaluation failures (e.g., query syntax errors)."

5. Re-notification (line 167): Explain the use case (e.g., "Prevents alert fatigue while ensuring ongoing issues aren't forgotten").

6. Intervals (line 200): This concept only appears in an example. Consider promoting it to its own subsection under "Scheduling Alerts" with an explanation of when to use interval-based monitoring vs simple cron schedules.

Properties to mention (with link to reference):

Add a note: "For advanced properties like glob, for, watermark, and timeout, see the Alert YAML Reference."

---

Developed in collaboration with Claude Code

[ericpgreen2]

Add a brief note explaining ISO 8601 duration format for users unfamiliar with this syntax (e.g., "PT1H = 1 hour, P1D = 1 day").

[ericpgreen2]

And/or link to the time syntax docs

[royendo]

not sure how this applies, i dont think we can use those durations in the alert YAML, its

[ericpgreen2]

Nice! I especially like the "Working Examples" section.