[Security][Quality] Improve docs for Security detections and alerts

[nastasha-solomon]

Summary

Fixes https://github.com/elastic/docs-content-internal/issues/797

Restructures the Detections and alerts section to reduce duplication, improve navigation, and give each page a clear purpose.

Key changes

Separated rule type content from shared settings
Created individual configuration guides for each rule type and a dedicated reference page for shared rule settings. The current documentation structure embeds UI-specific procedural steps inside conceptual and reference content, meaning any UI change requires touching multiple pages simultaneously. The proposed structure moves conceptual content, UI procedures, and field reference content to separate pages, so UI changes touch only the procedural pages.

Created decision guides for impt rule features

• Choose the right rule type - New page that helps users understand which rules fit their use case. Compares all rule types side by side and explains how building block rules fit into detection chains.
• Reduce noise and false positives - New page explains the distinct mechanisms for managing alert noise, when to use each mechanism, and how they work together.

Turned stubs into navigational hub pages

• Added descriptions to help readers find the right child page.

New pages requiring technical accuracy review

Rule type pages

File	Key areas to verify
custom-query.md	KQL/Lucene query guidance, saved query behavior, field reference
eql.md	Sequence query syntax, missing event detection, EQL settings
threshold.md	Group-by behavior, threshold count logic, synthetic alerts
indicator-match.md	Threat mapping, indicator index queries, value list usage
new-terms.md	History window sizing, multi-field combinations, first-seen logic
esql.md	Aggregating vs non-aggregating queries, alert deduplication, limitations
machine-learning.md	ML job selection, anomaly score thresholds, datafeed dependencies

Reference, decision guides, and rewritten/newly-written pages

File	Key areas to verify
rule-settings-reference.md	All shared field descriptions for completeness and accuracy
choose-the-right-rule-type.md	Comparison table accuracy, building block rules description
reduce-noise-and-false-positives.md	Decision table, key distinctions table, scenario walkthrough
write-investigation-guides.md	Markdown syntax table, Osquery steps, best practices
set-rule-data-sources.md	Per-rule index pattern behavior, cold/frozen tier filter accuracy
using-the-api.md	API endpoint paths and links for Stack and Serverless
validate-and-test-rules.md	Rule preview behavior, manual run side effects, DaC workflow accuracy, shadow deployment pattern

Hub pages (lower risk, spot-check)

before-you-begin.md, prebuilt-rules.md, create-a-detection-rule.md, advanced-data-source-configuration.md, detections-reference.md, rule-types.md, mitre-attack-coverage.md

Generative AI disclosure

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

• Yes
• No

Cursor, Claude

[github-actions]

Vale Linting Results

Summary: 12 warnings, 41 suggestions found

⚠️ Warnings (12)

File	Line	Rule	Message
solutions/security/detect-and-alert/custom-query.md	62	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'using' instead of 'via'.
solutions/security/detect-and-alert/custom-query.md	79	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'using' instead of 'via'.
solutions/security/detect-and-alert/custom-query.md	81	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'using' instead of 'via'.
solutions/security/detect-and-alert/esql.md	23	Elastic.DontUse	Don't use '...'.
solutions/security/detect-and-alert/esql.md	44	Elastic.DontUse	Don't use '...'.
solutions/security/detect-and-alert/esql.md	109	Elastic.DontUse	Don't use '...'.
solutions/security/detect-and-alert/install-manage-prebuilt-rules.md	106	Elastic.DontUse	Don't use 'Note that'.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	37	Elastic.QuotesPunctuation	Put punctuation outside the quotation marks.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	47	Elastic.QuotesPunctuation	Put punctuation outside the quotation marks.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	57	Elastic.QuotesPunctuation	Put punctuation outside the quotation marks.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	67	Elastic.QuotesPunctuation	Put punctuation outside the quotation marks.
troubleshoot/security/detection-rules.md	165	Elastic.DontUse	Don't use 'note that'.

💡 Suggestions (41)

File	Line	Rule	Message
solutions/security/detect-and-alert/before-you-begin.md	25	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/choose-the-right-rule-type.md	23	Elastic.Ellipses	In general, don't use an ellipsis.
solutions/security/detect-and-alert/choose-the-right-rule-type.md	35	Elastic.Wordiness	Consider using 'to' instead of 'in order to'.
solutions/security/detect-and-alert/choose-the-right-rule-type.md	91	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
solutions/security/detect-and-alert/custom-query.md	22	Elastic.WordChoice	Consider using 'efficient, basic' instead of 'simple', unless the term is in the UI.
solutions/security/detect-and-alert/custom-query.md	77	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
solutions/security/detect-and-alert/eql.md	89	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
solutions/security/detect-and-alert/esql.md	23	Elastic.Ellipses	In general, don't use an ellipsis.
solutions/security/detect-and-alert/esql.md	44	Elastic.Ellipses	In general, don't use an ellipsis.
solutions/security/detect-and-alert/esql.md	56	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/esql.md	98	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
solutions/security/detect-and-alert/esql.md	109	Elastic.Ellipses	In general, don't use an ellipsis.
solutions/security/detect-and-alert/indicator-match.md	72	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
solutions/security/detect-and-alert/install-manage-prebuilt-rules.md	81	Elastic.Semicolons	Use semicolons judiciously.
solutions/security/detect-and-alert/install-manage-prebuilt-rules.md	121	Elastic.Versions	Use 'or earlier' instead of 'or lower' when referring to versions.
solutions/security/detect-and-alert/machine-learning.md	82	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
solutions/security/detect-and-alert/mitre-attack-coverage.md	79	Elastic.WordChoice	Consider using 'deactivated, deselected, hidden, turned off, unavailable' instead of 'disabled', unless the term is in the UI.
solutions/security/detect-and-alert/new-terms.md	50	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/new-terms.md	70	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
solutions/security/detect-and-alert/prebuilt-rules.md	14	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	47	Elastic.FirstPerson	Use caution when using first-person pronouns such as 'my.'
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	90	Elastic.Wordiness	Consider using 'all' instead of 'all of '.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	102	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	102	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/rule-settings-reference.md	79	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/rule-settings-reference.md	109	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
solutions/security/detect-and-alert/rule-settings-reference.md	126	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
solutions/security/detect-and-alert/rule-settings-reference.md	162	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
solutions/security/detect-and-alert/rule-settings-reference.md	200	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
solutions/security/detect-and-alert/rule-settings-reference.md	202	Elastic.WordChoice	Consider using 'run, start' instead of 'execute', unless the term is in the UI.
solutions/security/detect-and-alert/rule-settings-reference.md	281	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
solutions/security/detect-and-alert/rule-settings-reference.md	291	Elastic.Wordiness	Consider using 'because' instead of 'since'.
solutions/security/detect-and-alert/rule-types.md	18	Elastic.Ellipses	In general, don't use an ellipsis.
solutions/security/detect-and-alert/set-rule-data-sources.md	40	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/set-rule-data-sources.md	48	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/threshold.md	70	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
solutions/security/detect-and-alert/tune-detection-rules.md	12	Elastic.Clone	Use cloning only when referring to cloning a GitHub repository or creating a copy that is linked to the original. Often confused with 'copy' and 'duplicate'.
solutions/security/detect-and-alert/update-prebuilt-rules.md	22	Elastic.Versions	Use 'or earlier' instead of 'or lower' when referring to versions.
solutions/security/detect-and-alert/using-the-rule-builder.md	28	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
solutions/security/detect-and-alert/validate-and-test-rules.md	50	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
troubleshoot/security/detection-rules.md	165	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.

---

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

[github-actions]

🔍 Preview links for changed docs

• solutions/security/detect-and-alert/advanced-data-source-configuration.md
• solutions/security/detect-and-alert/before-you-begin.md
• solutions/security/detect-and-alert/choose-the-right-rule-type.md
• solutions/security/detect-and-alert/create-a-detection-rule.md
• solutions/security/detect-and-alert/custom-query.md
• solutions/security/detect-and-alert/detections-reference.md
• solutions/security/detect-and-alert/eql.md
• solutions/security/detect-and-alert/esql.md
• solutions/security/detect-and-alert/indicator-match.md
• solutions/security/detect-and-alert/machine-learning.md

More links …

• solutions/security/detect-and-alert/mitre-attack-coverage.md
• solutions/security/detect-and-alert/new-terms.md
• solutions/security/detect-and-alert/prebuilt-rules.md
• solutions/security/detect-and-alert/reduce-noise-and-false-positives.md
• solutions/security/detect-and-alert/rule-settings-reference.md
• solutions/security/detect-and-alert/rule-types.md
• solutions/security/detect-and-alert/set-rule-data-sources.md
• solutions/security/detect-and-alert/threshold.md
• solutions/security/detect-and-alert/using-the-api.md
• solutions/security/detect-and-alert/using-the-rule-builder.md
• solutions/security/detect-and-alert/validate-and-test-rules.md
• solutions/security/detect-and-alert/write-investigation-guides.md
• explore-analyze/alerts-cases/alerts/alerting-setup.md
• explore-analyze/alerts-cases/alerts/rule-types.md
• manage-data/data-store/data-streams/logs-data-stream-configure.md
• manage-data/data-store/data-streams/logs-data-stream-integrations.md
• manage-data/data-store/data-streams/logs-data-stream.md
• reference/glossary/index.md
• reference/security/fields-and-object-schemas/alert-schema.md
• solutions/security/advanced-entity-analytics/anomaly-detection.md
• solutions/security/advanced-entity-analytics/entity-risk-scoring.md
• solutions/security/advanced-entity-analytics/machine-learning-job-rule-requirements.md
• solutions/security/cloud/d4c/get-started-with-d4c.md
• solutions/security/detect-and-alert.md
• solutions/security/detect-and-alert/about-building-block-rules.md
• solutions/security/detect-and-alert/add-detection-alerts-to-cases.md
• solutions/security/detect-and-alert/add-manage-exceptions.md
• solutions/security/detect-and-alert/create-manage-shared-exception-lists.md
• solutions/security/detect-and-alert/create-manage-value-lists.md
• solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md
• solutions/security/detect-and-alert/detections-privileges.md
• solutions/security/detect-and-alert/manage-detection-alerts.md
• solutions/security/detect-and-alert/manage-detection-rules.md
• solutions/security/detect-and-alert/monitor-rule-executions.md
• solutions/security/detect-and-alert/query-alert-indices.md
• solutions/security/detect-and-alert/rule-exceptions.md
• solutions/security/detect-and-alert/tune-detection-rules.md
• solutions/security/detect-and-alert/using-logsdb-index-mode-with-elastic-security.md
• solutions/security/detect-and-alert/view-detection-alert-details.md
• solutions/security/detect-and-alert/visualize-detection-alerts.md
• solutions/security/endpoint-response-actions/configure-third-party-response-actions.md
• solutions/security/endpoint-response-actions/isolate-host.md
• solutions/security/esql-for-security.md
• solutions/security/get-started/automatic-migration.md
• solutions/security/get-started/configure-advanced-settings.md
• solutions/security/get-started/elastic-security-requirements.md
• solutions/security/get-started/elastic-security-ui.md
• solutions/security/get-started/get-started-cloud-security.md
• solutions/security/get-started/get-started-detect-with-siem.md
• solutions/security/get-started/get-started-endpoint-security.md
• solutions/security/investigate/add-osquery-response-actions.md
• solutions/security/investigate/cases-requirements.md
• solutions/security/investigate/timeline-templates.md
• solutions/security/manage-elastic-defend/endpoint-protection-rules.md
• troubleshoot/security/detection-rules.md
• solutions/security/detect-and-alert/alert-suppression.md
• solutions/security/detect-and-alert/install-manage-prebuilt-rules.md
• solutions/security/detect-and-alert/requirements-privileges.md
• solutions/security/detect-and-alert/snooze-rule-actions.md
• solutions/security/detect-and-alert/update-prebuilt-rules.md