deduplicate

Author: colleenmcginnis

docs/_docset.yml

@@ -40,8 +40,8 @@ toc:
         children:
           - file: index.md
           - file: best-practices.md
-          - file: reference.md
           - file: content-patterns.md
+          - file: reference.md
       - file: branching-strategy.md
       - file: add-repo.md
       - file: release-new-version.md

docs/contribute/cumulative-docs/best-practices.md

@@ -63,6 +63,23 @@ For each type of applicability information, you can add `applies_to` metadata at
 % Reference: https://github.com/elastic/kibana/pull/229485/files#r2231850710
 % * Create hierarchy of versioned information??
 
+✅ Use `applies_to` tags when features change state (`preview`, `beta`, `ga`, `deprecated`, `removed`) or when
+availability differs across deployments and environments.
+
+✅ Use `applies_to` tags to indicate which product or deployment type the content applies to. This is mandatory for every
+page.
+
+✅ Use `applies_to` tags when features change state in a specific update or release.
+
+❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle
+changes.
+
+❌ You don’t need to tag every section or paragraph. Only do so if the context or applicability changes from what has
+been established earlier.
+
+❌ If the product is not versioned (meaning all users are always on the latest version, like in serverless or cloud), you
+do not need to tag a new GA feature.
+
 % TO DO: Open an issue to force the order in the code.
 ## Order of items
 
@@ -136,7 +153,7 @@ For the full list of supported `applies_to` keys, refer to [](/contribute/cumula
   * For example, you should not use version tagging when fixing typos,
     improving styling, or adding a long-forgotten setting.
 
-### Examples [versions-examples]
+### Example scenarios [versions-examples]
 
 * **A new feature is added to {{serverless-short}} or {{ecloud}}. How do I tag it?**
   Cumulative documentation is not meant to replace release notes. If a feature becomes available in {{serverless-short}} and doesn’t have a particular lifecycle state to call out (preview, beta, deprecated…), it does not need specific tagging.

docs/contribute/cumulative-docs/index.md

@@ -32,12 +32,12 @@ This extends to deprecations and removals: No information should be removed for
 
 To achieve this, the Markdown source files integrate a tagging system meant to identify:
 
-* **Product- or deployment-specific availability**: When content applies to or functions differently between products or deployment types (for example, Elastic Cloud Serverless or Elastic Cloud Hosted).
-* **Version-specific functionality**: When features are introduced, modified, or removed in specific versions including lifecycle changes (for example, going from Beta to GA).
+* When content applies to or functions differently between **products or deployment types**.
+* When features are introduced, modified, or removed in specific **versions** including lifecycle changes.
 
 This tagging system is mandatory for all of the public-facing documentation. We refer to it as `applies_to` tags or badges.
 
-For more detailed guidance on contributing to cumulative docs, refer to [](/contribute/cumulative-docs/best-practices.md).
+**For detailed guidance on contributing to cumulative docs, refer to [](/contribute/cumulative-docs/best-practices.md).**
 
 ### When _not_ to tag content
 

docs/syntax/_snippets/page-level-applies-examples.md

@@ -1,9 +1,9 @@
-There are 3 typical scenarios to start from:
+There are three typical scenarios to start from:
 
 * The documentation set or page is primarily about using or interacting with Elastic Stack components or the Serverless UI:
 
     ```yml
-    --- 
+    ---
     applies_to:
       stack: ga
       serverless: ga
@@ -13,10 +13,10 @@ There are 3 typical scenarios to start from:
 * The documentation set or page is primarily about orchestrating, deploying or configuring an installation (only include relevant keys):
 
   ```yml
-  --- 
+  ---
   applies_to:
     serverless: ga
-    deployment: 
+    deployment:
       ess: ga
       ece: ga
       eck: ga
@@ -27,7 +27,7 @@ There are 3 typical scenarios to start from:
 * The documentation set or page is primarily about a product following its own versioning schema:
 
   ```yml
-  --- 
+  ---
   applies_to:
     edot_ios: ga
   ---
@@ -36,11 +36,11 @@ There are 3 typical scenarios to start from:
 It can happen that it’s relevant to identify several or all of these dimensions for a page. Use your own judgement and check existing pages in similar contexts.
 
 ```yml
---- 
+---
 applies_to:
   stack: ga
   serverless: ga
-  deployment: 
+  deployment:
     ess: ga
     ece: ga
     eck: ga

docs/syntax/applies.md

@@ -11,50 +11,14 @@ To support this, source files use a tagging system to indicate:
 * Which Elastic products and deployment models the content applies to.
 * When a feature changes state relative to the base version.
 
-This is what the `applies_to` metadata is for. It can be used at the page, section, or inline level to specify
-applicability with precision.
+This is what the `applies_to` metadata is for. It can be used at the [page](#page-annotations),
+[section](#section-annotations), or [inline](#inline-annotations) level to specify applicability with precision.
 
-## `applies_to` tags in the output
-
-:::{include} /contribute/_snippets/tag-processing.md
-:::
-
-## When and where to use `applies_to`
-
-The `applies_to` metadata can be added at different levels in the documentation:
-
-* [Page-level](#page-annotations) metadata is **mandatory** and must be included in the frontmatter. This defines the
-  overall applicability of the page across products, deployments, and environments.
-* [Section-level](#section-annotations) annotations allow you to specify different applicability for individual sections
-  when only part of a page varies between products or versions.
-* [Inline](#inline-annotations) annotations allow fine-grained annotations within paragraphs or definition lists. This
-  is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the
-  surrounding content.
-
-### Dos and don’ts
-
-✅ Use `applies_to` tags when features change state (`preview`, `beta`, `ga`, `deprecated`, `removed`) or when
-availability differs across deployments and environments.
-
-✅ Use `applies_to` tags to indicate which product or deployment type the content applies to. This is mandatory for every
-page.
-
-✅ Use `applies_to` tags when features change state in a specific update or release.
-
-❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle
-changes.
-
-❌ You don’t need to tag every section or paragraph. Only do so if the context or applicability changes from what has
-been established earlier.
-
-❌ If the product is not versioned (meaning all users are always on the latest version, like in serverless or cloud), you
-do not need to tag a new GA feature.
-
-For detailed guidance, refer to [](/contribute/cumulative-docs/index.md).
+**For detailed guidance, refer to [](/contribute/cumulative-docs/index.md).**
 
 ## Syntax
 
-The `applies_to` metadata supports an [exhaustive list of keys](#structured-model).
+The `applies_to` metadata supports an [exhaustive list of keys](#key).
 
 When you write or edit documentation, only specify the keys that apply to that content.
 Each key accepts values with the following syntax:
@@ -71,21 +35,6 @@ Where:
 
 Note that a key without any value doesn't show any badge in the output.
 
-### Key
-
-:::{include} /_snippets/applies_to-key.md
-:::
-
-### Lifecycle
-
-:::{include} /_snippets/applies_to-lifecycle.md
-:::
-
-### Version
-
-:::{include} /_snippets/applies_to-version.md
-:::
-
 Versioned products require a `version` tag to be used with the `lifecycle` tag. See [Syntax](#syntax):
 
 ```
@@ -104,6 +53,22 @@ applies_to:
     observability: removed
 ```
 
+### Key
+
+:::{include} /_snippets/applies_to-key.md
+:::
+
+### Lifecycle
+
+:::{include} /_snippets/applies_to-lifecycle.md
+:::
+
+### Version
+
+:::{include} /_snippets/applies_to-version.md
+:::
+
+
 ## Examples
 
 ### Lifecycle examples