diff --git a/contribute-docs/content-types/changelogs.md b/contribute-docs/content-types/changelogs.md index 45a4262329..6d2f95ada9 100644 --- a/contribute-docs/content-types/changelogs.md +++ b/contribute-docs/content-types/changelogs.md @@ -5,8 +5,6 @@ description: "Guidelines for writing effective release notes content in changelo # Changelogs -% Title and technical-formatting guidance updated (base-form verbs, {{esql}}, cleanup checklist, YAML quoting note) — documentation agent, 2026-05-11. - This page provides guidelines for writing useful and consistent changelogs, which are the building blocks of Elastic release notes. Use this content type and the associated schema to draft new changelogs or to evaluate existing content. @@ -211,21 +209,23 @@ Include a description when: Follow these best practices: - **Keep it concise**: Use a maximum of 600 characters. -- **Focus on user value**: Explain what users can do or what problems are solved. +- **Use third-person present**: Titles stay base-form imperative (*Fix*, *Add*); descriptions do not (*Fixes*, *Adds*, *Enables*, *Improves*, *Updates*, or *Removes* depending on type). +- **Focus on user value**: Explain what users can do or what problems are solved. Avoid filler such as "This enhancement allows you to..." - **Provide context**: Help users understand when or why they would use this. - **Include relevant details**: Describe configuration changes, API changes, or behavioral differences. - **Use code blocks**: Consider the layout of your configuration examples and code snippets. #### Good description examples -- This enhancement allows you to configure custom authentication providers through the security settings. Previously, only built-in providers were supported. -- Fix an issue where queries with date range filters could cause excessive memory usage in clusters with many shards. The change optimizes memory allocation for date range queries. +- Adds support for custom authentication providers through the security settings. Previously, only built-in providers were supported. +- Fixes excessive memory usage for queries with date range filters in clusters with many shards by optimizing memory allocation. #### Poor description examples - "Internal refactoring": Doesn't explain user impact. - "See PR #12345 for details": Doesn't provide information, only a reference. - Repeating the title verbatim, which adds no value. +- "Fixed Fleet package policy bulk creation": Past tense; use *Fixes*. ### Write about user impact and actions @@ -267,6 +267,7 @@ Avoid these common mistakes: - **Being too vague**: "Bug fixes and performance improvements" doesn't help users understand what changed. - **Including unnecessary technical details**: Skip internal architecture changes unless they affect users. - **Shipping PR-style titles unchanged**: Omit `feat:`/`fix:` prefixes, auto-implement labels, and bracketed team tags—rewrite for users (see [Title cleanup checklist](#title-cleanup-checklist)). +- **Mixing title and description verb forms**: Don't open a description with *Fix* or *Fixed*. Titles use *Fix*; descriptions use *Fixes*. ## Examples diff --git a/contribute-docs/style-guide/formatting.md b/contribute-docs/style-guide/formatting.md index df5038d108..9f7efb5a56 100644 --- a/contribute-docs/style-guide/formatting.md +++ b/contribute-docs/style-guide/formatting.md @@ -590,27 +590,25 @@ The goal of our release notes is to provide clear, scannable, and actionable inf Follow these general guidelines: -* To maintain an immediate and professional tone, every entry must start with a present-tense active verb (for example, _Adds_, _Fixes_, _Updates_, _Enhances_, _Removes_). +* To maintain an immediate and professional tone, every entry must start with a present-tense active verb (for example, _Add_, _Fix_, _Update_, _Enhance_, _Remove_). * Focus on the "what" and the "why." Avoid filler phrases like, "The system now allows you to..." -* Bold all specific page titles, buttons, icon names, modal/dialog titles, API names, and column names. For a comprehensive list, refer to our [guidance on using bold text](#bold-strong). + * Use monospace formatting for file paths, parameters, field or CLI commands. For a comprehensive list, refer to our [guidance on using monospace text](#monospace-code). :::{dropdown} Release note examples - ✔️ **Do**: Adds a search bar to the **Dashboard** page. + ✔️ **Do**: Add a search bar to the Dashboard page - ✔️ **Do**: Adds a **View in Discover** link to APM rule-based alert details to view related documents in Discover. + ✔️ **Do**: Add a "View in Discover" link to APM rule-based alert details to view related documents in Discover - ✔️ **Do**: Adds the `xpack.productDocBase.artifactRepositoryProxyUrl` setting to `kibana.yml`. + ✔️ **Do**: Add the `xpack.productDocBase.artifactRepositoryProxyUrl` setting to `kibana.yml` - ✔️ Adds support for `doc_values` to text fields. + ✔️ **Do**: Add support for `doc_values` to text fields - ❌ **Don't**: From the action menu (...), click the **Delete** button to delete the job. - - ❌ **Don't**: Now there's an auto-push option for case connectors, enabling automatic case - synchronization. + ❌ **Don't**: Now there's an auto-push option for case connectors, enabling automatic case synchronization ::: - ## Redaction of sensitive information End-user documentation may contain screen captures and examples that show