Skip to content

Alerts and cases first 20 lines optimization #4103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Alerts and cases first 20 lines optimization #4103

wants to merge 2 commits into from

Conversation

@florent-leborgne
Copy link
Contributor

@florent-leborgne florent-leborgne commented Nov 26, 2025

Summary

This PR updates the page opening of all Alerts and cases docs pages. In particular:

  • Check that the frontmatter is correct and contains the right metadata
  • More generally, frontmatter is often missing an intentional description in many docs files
  • Optimized H1
  • Optimized page intro based on basic content types (tutorial/explanation/guide/reference) that provides better context and sets better expectations

These changes follow instructions provided to AI following an onweek project: https://github.com/florent-leborgne/mi-instructions

Generative AI disclosure

  1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?
  • Yes
  • No

Tool(s) and model(s) used: Cursor with Claude Sonnet 4.5

@florent-leborgne florent-leborgne requested review from a team as code owners November 26, 2025 13:55
@florent-leborgne florent-leborgne marked this pull request as draft November 26, 2025 13:55
@github-actions
Copy link

github-actions bot commented Nov 26, 2025 •
edited
Loading

Vale Linting Results

Summary: 24 suggestions found

💡 Suggestions (24)
File Line Rule Message
explore-analyze/alerts-cases.md 39 Elastic.Capitalization '[watcher-overview]' should use sentence-style capitalization.
explore-analyze/alerts-cases/alerts/create-manage-rules.md 15 Elastic.WordChoice Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI.
explore-analyze/alerts-cases/alerts/create-manage-rules.md 15 Elastic.WordChoice Consider using 'turn off, silence' instead of 'mute', unless the term is in the UI.
explore-analyze/alerts-cases/alerts/rule-type-es-query.md 13 Elastic.Capitalization 'query rule [rule-type-es-query]' should use sentence-style capitalization.
explore-analyze/alerts-cases/alerts/rule-type-es-query.md 15 Elastic.Acronyms 'DSL' has no definition.
explore-analyze/alerts-cases/watcher.md 18 Elastic.Capitalization '[watcher]' should use sentence-style capitalization.
explore-analyze/alerts-cases/watcher.md 34 Elastic.Wordiness Consider using 'these' instead of 'All of these'.
explore-analyze/alerts-cases/watcher.md 38 Elastic.EmDashes Don't put a space before or after a dash.
explore-analyze/alerts-cases/watcher/action-conditions.md 9 Elastic.WordChoice Consider using 'run, start' instead of 'execute', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/action-conditions.md 14 Elastic.WordChoice Consider using 'run, start' instead of 'execute', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/action-conditions.md 14 Elastic.WordChoice Consider using 'run, start' instead of 'execute', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/action-foreach.md 8 Elastic.WordChoice Consider using 'run, start' instead of 'execute', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/actions.md 9 Elastic.WordChoice Consider using 'run, start' instead of 'execute', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/condition.md 14 Elastic.WordChoice Consider using 'run, start' instead of 'execute', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/encrypting-data.md 13 Elastic.Acronyms 'SMTP' has no definition.
explore-analyze/alerts-cases/watcher/execute-watch.md 13 Elastic.WordChoice Consider using 'run, start' instead of 'execute', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/input-simple.md 9 Elastic.WordChoice Consider using 'efficient' instead of 'simple', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/input-simple.md 14 Elastic.WordChoice Consider using 'efficient' instead of 'simple', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/input.md 14 Elastic.WordChoice Consider using 'efficient' instead of 'simple', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/schedule-types.md 13 Elastic.WordChoice Consider using 'efficient' instead of 'simple', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/trigger-schedule.md 14 Elastic.Acronyms 'UTC' has no definition.
explore-analyze/alerts-cases/watcher/trigger-schedule.md 14 Elastic.Acronyms 'NTP' has no definition.
explore-analyze/alerts-cases/watcher/watcher-getting-started.md 13 Elastic.WordChoice Consider using 'run, start' instead of 'execute', unless the term is in the UI.
explore-analyze/alerts-cases/watcher/watcher-limitations.md 12 Elastic.Capitalization 'limitations [watcher-limitations]' should use sentence-style capitalization.

@florent-leborgne
Copy link
Contributor Author

florent-leborgne commented Nov 26, 2025

@nastasha-solomon can you take a quick look and let me know how you feel about these changes? I went through the same exercise with other docs folders that I own or know but would be curious to get your thoughts on this.
For the record: nothing in there is manual, it's all defined based on the same instructions. The goal is to make this work for as many doc sections as possible.

The ask here is not to review everything (unless you find that the changes are good), but first and foremost to assess if AI is getting some patterns wrong, resulting in losing interesting information instead of improving page starts.

@github-actions
Copy link

github-actions bot commented Nov 26, 2025

🔍 Preview links for changed docs

More links …

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@florent-leborgne