From 3467ba6e91f339e68282c4e92819e7089452b35b Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 26 Jan 2026 16:43:24 -0500 Subject: [PATCH 1/5] dimensions --- contribute-docs/_snippets/dimensions.md | 9 ++ .../cumulative-docs/example-scenarios.md | 96 +++++++++++++------ .../how-to/cumulative-docs/guidelines.md | 26 ++++- .../how-to/cumulative-docs/reference.md | 15 ++- 4 files changed, 115 insertions(+), 31 deletions(-) create mode 100644 contribute-docs/_snippets/dimensions.md diff --git a/contribute-docs/_snippets/dimensions.md b/contribute-docs/_snippets/dimensions.md new file mode 100644 index 0000000000..726c272285 --- /dev/null +++ b/contribute-docs/_snippets/dimensions.md @@ -0,0 +1,9 @@ +The `applies_to` keys fall into three dimensions: + +| Dimension | Values | +| --- | --- | +| Stack/Serverless | `stack`, `serverless` | +| Deployment | `deployment` (with subkeys: `ece`, `eck`, `ech`, `self`), `serverless` | +| Product | `product` (with subkeys: APM agents, EDOT items, etc.) | + +Use only one dimension at the page level. `serverless` can appear in both the Stack/Serverless and Deployment dimensions. diff --git a/contribute-docs/how-to/cumulative-docs/example-scenarios.md b/contribute-docs/how-to/cumulative-docs/example-scenarios.md index 86300dc5b7..c39d6f8c6b 100644 --- a/contribute-docs/how-to/cumulative-docs/example-scenarios.md +++ b/contribute-docs/how-to/cumulative-docs/example-scenarios.md @@ -26,7 +26,6 @@ the Serverless UI, add both the `stack` and `serverless` keys to the `applies_to :::{include} /contribute-docs/_snippets/stack-serverless-lifecycle-example.md ::: - ## Section applicability differs from page-level applicability [page-section-varies] When a section has different applicability than the applicability indicated at the @@ -174,7 +173,7 @@ applies_to: ```{applies_to} deployment: ech: ga -serverless: ga + serverless: ga ``` [...] @@ -187,6 +186,48 @@ Likewise, when the difference is specific to just one paragraph or list item, th Just the syntax slightly differs so that it stays inline: `` {applies_to}`ech: ga` {applies_to}`serverless: ga` ``. ::: +## Choosing a primary dimension [primary-dimension] + +When your content has requirements that span multiple dimensions, choose one dimension as the primary for the page-level `applies_to` frontmatter, and document secondary dimension information as requirements, prerequisites, or in tagged sections. + +:::{tip} +Use only one dimension at the page level. If you need to communicate information from another dimension, add it as requirements in prose, prerequisites sections, or use section-level or inline `applies_to` badges for specific content that varies. +::: + +For example, a page about a Kibana feature (Stack/Serverless dimension) might have deployment-specific configuration requirements. Use the Stack/Serverless dimension at the page level, and document deployment-specific information in prose or tagged sections: + +```` +--- +applies_to: + stack: ga + serverless: ga +--- + +# Configure Kibana feature + +This feature is available in Elastic Stack 9.0+ and Serverless. + +## Prerequisites + +* If using ECE, requires ECE 4.0+ or later. + +## Configuration + +[... main configuration steps ...] + +## Deployment-specific settings + +```{applies_to} +deployment: + ech: ga + ece: ga 4.0+ +``` + +For Elastic Cloud Hosted and Elastic Cloud Enterprise deployments, you must also configure the following setting: + +[...] +```` + ## Functionality is added to an unversioned product [unversioned-added] When functionality is _first added_ to an unversioned product/deployment mode, @@ -316,7 +357,6 @@ serverless: ga :::: ::::: - ## Functionality is removed [removed] When the functionality described in any level of content is removed, @@ -374,6 +414,31 @@ you can remove the content altogether regardless of whether it is versioned or u If the functionality was only ever available in an unversioned product or deployment mode, remove the content altogether. +## Functionality is added to multiple patch versions [multiple-patch] + +Sometimes, features and enhancements slip through into patch versions, and the same functionality might be added for the first time to multiple patch versions at the same time. + +- **Standard case**: Our docs are aligned with the latest patch of any given minor version. That means that in most cases, we don't need to call out the exact patch version that introduced a change (that's for the release notes). +- **Exceptions**: In rare cases, it can happen that the change is important enough to be explicitly called out in the docs with a precise patch-level information. In that case, you can add a callout and indicate patch-level versions using plain text to explain the change. + +For example, on the [HTTP JSON input](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-httpjson) page, the `terminate` helper function was added to a 9.0.x and 9.1.x patch version at the same time. Since the new functionality is available in the latest patch of both 9.0.x and 9.1.x, use the earlier version: 9.0.x. + +:::::{tab-set} +::::{tab-item} Image +:::{image} ./images/example-multiple-patch.png +:screenshot: +:alt: +::: +:::: +::::{tab-item} Code +```markdown +* `terminate`: exits the template without falling back to the default value + and without causing an error. It takes a single string argument that is + logged in debug logging. {applies_to}`stack: ga 9.1.2+!` {applies_to}`stack: ga 9.0.6+!` +``` +:::: +::::: + ## Code block content varies [code-block] Often the content in a code block will vary between situations (versions, deployment types, etc). @@ -635,28 +700,3 @@ _Work in progress._ % **When to use headings**: % **Best practices**: % **Example**: - -## Functionality is added to multiple patch versions [multiple-patch] - -Sometimes, features and enhancements slip through into patch versions, and the same functionality might be added for the first time to multiple patch versions at the same time. - -- **Standard case**: Our docs are aligned with the latest patch of any given minor version. That means that in most cases, we don't need to call out the exact patch version that introduced a change (that's for the release notes). -- **Exceptions**: In rare cases, it can happen that the change is important enough to be explicitly called out in the docs with a precise patch-level information. In that case, you can add a callout and indicate patch-level versions using plain text to explain the change. - -For example, on the [HTTP JSON input](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-httpjson) page, the `terminate` helper function was added to a 9.0.x and 9.1.x patch version at the same time. Since the new functionality is available in the latest patch of both 9.0.x and 9.1.x, use the earlier version: 9.0.x. - -:::::{tab-set} -::::{tab-item} Image -:::{image} ./images/example-multiple-patch.png -:screenshot: -:alt: -::: -:::: -::::{tab-item} Code -```markdown -* `terminate`: exits the template without falling back to the default value - and without causing an error. It takes a single string argument that is - logged in debug logging. {applies_to}`stack: ga 9.1.2+!` {applies_to}`stack: ga 9.0.6+!` -``` -:::: -::::: diff --git a/contribute-docs/how-to/cumulative-docs/guidelines.md b/contribute-docs/how-to/cumulative-docs/guidelines.md index cfe465ed50..4e31352604 100644 --- a/contribute-docs/how-to/cumulative-docs/guidelines.md +++ b/contribute-docs/how-to/cumulative-docs/guidelines.md @@ -55,6 +55,25 @@ For each type of applicability information, you can add `applies_to` metadata at For a full syntax reference for page, section, and inline level `applies_to` annotations, refer to [the applies_to syntax guide](https://elastic.github.io/docs-builder/syntax/applies). +## Dimensions + +The `applies_to` keys fall into three dimensions based on the products and user contexts being documented on the page: + +| Dimension | Description | Values | +| --- | --- | --- | +| Stack/Serverless | Represents the version or "flavor" of the core Elastic platform. Use when your content is primarily about features, functionality, or workflows that vary based on which version of the Elastic platform users are running. | `stack`, `serverless` | +| Deployment | Represents how the Elastic platform is deployed and orchestrated. Use when your content is primarily about deployment, configuration, or management tasks that differ based on how users have deployed Elasticsearch and Kibana. | `deployment` (with subkeys: `ece`, `eck`, `ech`, `self`), `serverless` | +| Product | Represents software outside the core Elastic platform that has its own versioning scheme. Use when your content is primarily about features or functionality specific to these standalone products. | `product` (with subkeys: APM agents, EDOT items, etc.) | + +Most pages focus on one primary context, so you should only use keys from one dimension at the page level. For example, a page about a Kibana feature would use the Stack/Serverless dimension, while a page about configuring cluster settings would use the Deployment dimension. + +### Dimension usage tips + +* `serverless` can appear in both the Stack/Serverless dimension and the Deployment dimension. This is because Serverless acts as both a "version" or "flavor" of the stack (like `stack`), and a unique deployment type with specialized management processes (like `ece` or `eck`). +* The versioned Elastic Stack (`stack`) can be deployed across ECE, ECK, ECH, and self-managed clusters. When orchestration features are shared or similar across these deployment types, the feature is usually part of the core platform, and you can use `stack` in the Stack/Serverless dimension rather than specifying each deployment type individually. +* If your content has nuances specific to another dimension, determine the "primary" dimension for the page level `applies_to` frontmatter, and then add the secondary dimension information as requirements, or as tagged sections later on the page. +* To determine the primary dimension of a page, consider what the main focus of the page is, what most of the content relates to, and what context users will primarily identify with when they arrive at the page. For example, if a page is primarily about a Kibana feature but mentions deployment-specific configuration, use the Stack/Serverless dimension as primary. + ## General guidelines ### When to tag content @@ -149,14 +168,13 @@ For example this syntax: deployment: ece: ga self: ga -stack: ga serverless: ga ``` ```` Results in the badges in this order: -{applies_to}`{ deployment: { ece: ga, self: ga }, stack: ga, serverless: ga }` +{applies_to}`{ deployment: { ece: ga, self: ga }, serverless: ga }` ## Product and deployment model applicability [products-and-deployment-models] @@ -167,10 +185,14 @@ refer to [](reference.md#key). * **Always include page-level product and deployment model applicability information**. This is _mandatory_ for all pages. +* **Use only one dimension per page at the page level.** + Choose either the Stack/Serverless dimension, the Deployment dimension, or the Product dimension. + See [Dimensions](#dimensions) for more information. * **Determine if section or inline applicability information is necessary.** This _depends on the situation_. * For example, if a portion of a page is applicable to a different context than what was specified at the page level, clarify in what context it applies using section or inline `applies_to` badges. + * Section-level and inline annotations can reference items from a different dimension than the page-level dimension when needed to clarify specific requirements. % Source: https://elastic.github.io/docs-builder/versions/#defaults-and-hierarchy * **Do not assume a default product or deployment type.** Treat all products and deployment types equally. Don't treat one as the "base" and the other as the "exception". diff --git a/contribute-docs/how-to/cumulative-docs/reference.md b/contribute-docs/how-to/cumulative-docs/reference.md index b199205237..420d277fd0 100644 --- a/contribute-docs/how-to/cumulative-docs/reference.md +++ b/contribute-docs/how-to/cumulative-docs/reference.md @@ -1,7 +1,6 @@ # Quick reference :::{note} -This content is still in development. If you have questions about how to write cumulative documentation while contributing, reach out to **@elastic/docs** in the related GitHub issue or PR. ::: @@ -14,6 +13,20 @@ The `applies_to` directive uses the following format: This page provides minimal reference information on the `applies_to` directive. For more detailed information, refer to [the applies_to syntax guide](https://elastic.github.io/docs-builder/syntax/applies). +## Dimensions + +The `applies_to` keys fall into three dimensions: + +| Dimension | Values | +| --- | --- | +| Stack/Serverless | `stack`, `serverless` | +| Deployment | `deployment` (with subkeys: `ece`, `eck`, `ech`, `self`), `serverless` | +| Product | `product` (with subkeys: APM agents, EDOT items, etc.) | + +Use only one dimension at the page level. `serverless` can appear in both the Stack/Serverless and Deployment dimensions. [Learn more](/contribute-docs/how-to/cumulative-docs/guidelines.md#dimensions). + +## Key reference + ## key :::{include} /contribute-docs/_snippets/applies_to-key.md From 212029804285afa82f808216de72f33e7e3bcfe6 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 26 Jan 2026 16:54:13 -0500 Subject: [PATCH 2/5] polish --- .../how-to/cumulative-docs/badge-placement.md | 2 +- .../cumulative-docs/example-scenarios.md | 79 +++++++++++-------- .../how-to/cumulative-docs/guidelines.md | 2 +- 3 files changed, 48 insertions(+), 35 deletions(-) diff --git a/contribute-docs/how-to/cumulative-docs/badge-placement.md b/contribute-docs/how-to/cumulative-docs/badge-placement.md index 339a1f79d3..801444ce05 100644 --- a/contribute-docs/how-to/cumulative-docs/badge-placement.md +++ b/contribute-docs/how-to/cumulative-docs/badge-placement.md @@ -39,7 +39,7 @@ There are more specific guidelines on badge placement to follow when using speci ### Page frontmatter -Use [`applies_to` in a page's frontmatter](https://elastic.github.io/docs-builder/syntax/applies#syntax) to provide signals that a page applies to the reader. +Use [`applies_to` in a page's frontmatter](https://elastic.github.io/docs-builder/syntax/applies#syntax) to provide signals that a page applies to the reader. You should use only one `applies_to` [dimension](/contribute-docs/how-to/cumulative-docs/guidelines.md#dimensions) at the page level. This dimension represent's the user's primary context, whether it's a platform version, deployment type, or supporting piece of software. ::::{warning} Do **not** use [section-level](https://elastic.github.io/docs-builder/syntax/applies#section-level) or [inline annotations](https://elastic.github.io/docs-builder/syntax/applies#inline-level) with the page title. diff --git a/contribute-docs/how-to/cumulative-docs/example-scenarios.md b/contribute-docs/how-to/cumulative-docs/example-scenarios.md index c39d6f8c6b..7cbceab1dc 100644 --- a/contribute-docs/how-to/cumulative-docs/example-scenarios.md +++ b/contribute-docs/how-to/cumulative-docs/example-scenarios.md @@ -5,33 +5,38 @@ navigation_title: Example scenarios # Cumulative docs example scenarios :::{note} -This content is still in development. If you have questions about how to write cumulative documentation while contributing, reach out to **@elastic/docs** in the related GitHub issue or PR. ::: Browse common scenarios you might run into as a docs contributor that require different approaches to labeling cumulative docs. +While you can use any of these tools at any stage, the tools and approaches you use for cumulative documentation often differ depending on the maturity and complexity of your documentation. The scenarios below are organized by documentation stage to help you find the right approach for your situation. + :::{note} Screenshots might not exactly match the example pages linked to. ::: -## Content applies to both stateful and serverless [stateful-serverless] +## Early stage: New features and simple documentation + +When you're documenting a new feature or creating simple documentation, start with basic page-level tagging and simple refinements. + +### Content applies to both stateful and serverless [stateful-serverless] If an entire page is primarily about using or interacting with both Elastic Stack components and the Serverless UI, add both the `stack` and `serverless` keys to the `applies_to` in the frontmatter. -### If released in Serverless, but not yet released in Elastic Stack +#### If released in Serverless, but not yet released in Elastic Stack :::{include} /contribute-docs/_snippets/stack-serverless-lifecycle-example.md ::: -## Section applicability differs from page-level applicability [page-section-varies] +### Section applicability differs from page-level applicability [page-section-varies] When a section has different applicability than the applicability indicated at the page level in the frontmatter, use section-level `applies_to` badges. -### If labeling serverless vs. stateful [page-section-varies-product] +#### If labeling serverless vs. stateful [page-section-varies-product]