Skip to content

Document dimensions for applies_to tags #4819

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

Open
shainaraskas wants to merge 6 commits into
base: main
Choose a base branch
from
+162 −65
Open

Document dimensions for applies_to tags #4819

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3467ba6
dimensions
shainaraskas Jan 26, 2026
2120298
polish
shainaraskas Jan 26, 2026
a61d4a3
Update contribute-docs/how-to/cumulative-docs/guidelines.md
shainaraskas Jan 26, 2026
8fdde4f
ten second tidy
shainaraskas Jan 27, 2026
f888e9f
Merge branch 'dimensions' of github.com:elastic/docs-content into dim…
shainaraskas Jan 27, 2026
9cbb3ef
additional clarification
shainaraskas Jan 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions contribute-docs/_snippets/dimensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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, including those for APM agents, EDOT SDKs, and client libraries) |

Use only one dimension at the page level. `serverless` can appear in both the Stack/Serverless and Deployment dimensions.
2 changes: 1 addition & 1 deletion contribute-docs/how-to/cumulative-docs/badge-placement.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
175 changes: 114 additions & 61 deletions contribute-docs/how-to/cumulative-docs/example-scenarios.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,34 +5,38 @@
# 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 basics

When you're documenting a new feature or writing new guides or procedures, start with page-level tagging and section-level clarifications.

### 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]

Check warning on line 39 in contribute-docs/how-to/cumulative-docs/example-scenarios.md

View workflow job for this annotation

GitHub Actions / preview / vale 

Elastic.Latinisms: Latin terms and abbreviations are a common source of confusion. Use 'versus' instead of 'vs'.

<!--
TO DO: Consider other alternative titles:
Expand Down Expand Up @@ -115,7 +119,7 @@
Just the syntax slightly differs so that it stays inline: `` {applies_to}`serverless: unavailable` ``.
:::

### If labeling deployment modes [page-section-varies-deployment]
#### If labeling deployment modes [page-section-varies-deployment]

<!--
TO DO: Consider other alternative titles:
Expand Down Expand Up @@ -174,7 +178,7 @@
```{applies_to}
deployment:
ech: ga
serverless: ga
serverless: ga
```

[...]
Expand All @@ -187,15 +191,61 @@
Just the syntax slightly differs so that it stays inline: `` {applies_to}`ech: ga` {applies_to}`serverless: ga` ``.
:::

## Functionality is added to an unversioned product [unversioned-added]
### Choosing a primary dimension for your page [primary-dimension]

When your content has requirements that span multiple [dimensions](/contribute-docs/how-to/cumulative-docs/guidelines.md), 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:

[...]
````

## Mid-stage: Features evolve and documentation needs updates

As features change over time, you'll need to update your documentation to reflect lifecycle changes, additions, and removals.

### Functionality is added to an unversioned product [unversioned-added]

When functionality is _first added_ to an unversioned product/deployment mode,
how it is labeled depends on if the functionality is in technical preview, beta, or GA.

### If the section lifecycle is the same as the page level [unversioned-added-same]
#### If the section lifecycle is the same as the page level [unversioned-added-same]

For example, on the [Project settings](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/project-settings#obs-serverless-project-features) page we added content about the Observability Logs Essentials feature tier, that was added to Serverless in GA.
Since the page's frontmatter already includes `serverless: ga`, there is no need to label the added content.
Because the page's frontmatter already includes `serverless: ga`, there is no need to label the added content.

However, if the functionality is also applicable to a specific version of a versioned product/deployment mode,
label the content with both versioned and unversioned applicability information.
Expand Down Expand Up @@ -224,18 +274,18 @@

[...]

#### Tables
##### Tables

**Density** {applies_to}`stack: ga 9.1+` {applies_to}`serverless: ga`
: Make the table more or less compact. Choose between **Compact**, **Normal** (default), and **Expanded**.
```
::::
:::::

### If the section lifecycle is different than the page level [unversioned-added-different]
#### If the section lifecycle is different than the page level [unversioned-added-different]

For example, on the [Dashboard controls](https://www.elastic.co/docs/explore-analyze/dashboards/add-controls#add-esql-control) page we added content about new ES|QL controls functionality that was added to Serverless in preview.
Since this is different than the page-level applicability in the frontmatter, `serverless: ga`,
Because this is different than the page-level applicability in the frontmatter, `serverless: ga`,
label the content about the new functionality with `serverless: preview`.

:::::{tab-set}
Expand Down Expand Up @@ -266,7 +316,7 @@
::::
:::::

## Functionality changes lifecycle state [lifecycle-changed]
### Functionality changes lifecycle state [lifecycle-changed]

When the functionality described in any content changes lifecycle state,
how it is labeled varies by whether the product/deployment mode is versioned or unversioned.
Expand Down Expand Up @@ -303,7 +353,7 @@

[...]

### Assign colors to terms [assign-colors-to-terms]
##### Assign colors to terms [assign-colors-to-terms]

```{applies_to}
stack: ga 9.1+, preview =9.0
Expand All @@ -316,20 +366,19 @@
::::
:::::


## Functionality is removed [removed]
### Functionality is removed [removed]

When the functionality described in any level of content is removed,
how to handle it varies by which lifecycle it was in before being removed and
whether the product/deployment mode is versioned or unversioned.

### If a GA or deprecated feature is removed from a versioned product
#### If a GA or deprecated feature is removed from a versioned product

For example, we removed the `securitySolution:enableVisualizationsInFlyout` setting that was described on the
[Configure advanced settings](https://www.elastic.co/docs/solutions/security/get-started/configure-advanced-settings)
page from the Elastic Stack in 9.1.0 and from Serverless around the same time.
Since this this functionality is still available before 9.1.0, we need that content to continue to be
Because this functionality is still available before 9.1.0, we need that content to continue to be
available to users on Elastic Stack earlier versions while communicating to users on newer versions

Check notice on line 381 in contribute-docs/how-to/cumulative-docs/example-scenarios.md

View workflow job for this annotation

GitHub Actions / preview / vale 

Elastic.Versions: Use 'later versions' instead of 'newer versions' when referring to versions.
that it is no longer available.

:::::{tab-set}
Expand Down Expand Up @@ -364,22 +413,51 @@
::::
:::::

### If a beta or technical preview feature is removed [beta-removed]
#### If a beta or technical preview feature is removed [beta-removed]

If the functionality was only ever available in beta or technical preview before being removed,
you can remove the content altogether regardless of whether it is versioned or unversioned.

### If a feature is removed from an unversioned product
#### If a feature is removed from an unversioned product

If the functionality was only ever available in an unversioned product or deployment mode,
remove the content altogether.

## Code block content varies [code-block]
### 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.

Check notice on line 433 in contribute-docs/how-to/cumulative-docs/example-scenarios.md

View workflow job for this annotation

GitHub Actions / preview / vale 

Elastic.Wordiness: Consider using 'because' instead of 'Since'.

:::::{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+!`
```
::::
:::::

## Mature and complex: Documentation with many variations

When your documentation has accumulated many variations across different contexts, you'll need more sophisticated approaches to present the differences clearly.

### Code block content varies [code-block]

Often the content in a code block will vary between situations (versions, deployment types, etc).
There are a couple possible solutions.

### Solution A: Use a code callout [code-block-callout]
#### Solution A: Use a code callout [code-block-callout]

Using a code callout is the lightest-touch solution, but might not be sufficient in all cases.

Expand All @@ -402,7 +480,7 @@
:screenshot:
::::

### Solution B: Use applies switch tabs [code-block-tabs]
#### Solution B: Use applies switch tabs [code-block-tabs]

**When to use applies switch tabs**: If using a [code callout](#code-block-callout) isn't appropriate.

Expand Down Expand Up @@ -449,11 +527,11 @@
:::::
::::::

## Workflows vary [workflow]
### Workflows vary [workflow]

When one or more steps in a process differs.

### Solution A: Use inline `applies_to` [workflow-inline]
#### Solution A: Use inline `applies_to` [workflow-inline]

Using inline `applies_to` badges to a few line items in an ordered list is the lightest-touch solution,
but might not be sufficient in all cases.
Expand Down Expand Up @@ -490,7 +568,7 @@
::::
:::::

### Solution B: Use applies switch tabs [workflow-tabs]
#### Solution B: Use applies switch tabs [workflow-tabs]

Applies switch tabs are minimally disruptive in many situations.

Expand Down Expand Up @@ -548,7 +626,7 @@

::::::

### Solution C: Use sibling pages [workflow-sibling-pages]
#### Solution C: Use sibling pages [workflow-sibling-pages]

Sibling pages are a last resort when no other solutions are appropriate.

Expand All @@ -572,11 +650,11 @@
* [Cloud Hosted deployment billing dimensions](https://elastic.co/docs/deploy-manage/cloud-organization/billing/cloud-hosted-deployment-billing-dimensions)
* [{{serverless-short}} project billing dimensions](https://elastic.co/docs/deploy-manage/cloud-organization/billing/serverless-project-billing-dimensions)

## Screenshots vary [screenshot]
### Screenshots vary [screenshot]

Sometimes the UI differs between versions, deployment types or other conditions.

### Solution A: Use applies switch tabs [screenshot-tabs]
#### Solution A: Use applies switch tabs [screenshot-tabs]

**When to use applies switch tabs**:
* When the screenshot shows significantly different interfaces or workflows for each product, deployment type, or version.
Expand All @@ -588,7 +666,7 @@
**Example**: As of the Elastic Stack 9.1.0 release, there are no examples of this approach being used in live docs
except for with images used in workflows.

### Solution B: Add a note [screenshot-note]
#### Solution B: Add a note [screenshot-note]

In cases where only a small visual detail differs (for example, a button label or icon), it’s often more efficient to add a note rather than creating tabbed screenshots.

Expand All @@ -604,15 +682,15 @@
**Example**: As of the Elastic Stack 9.1.0 release, there are no examples of this approach being used in live docs
except for with images used in workflows.

### Solution C: Keep the screenshot aligned with the latest version [screenshot-latest]
#### Solution C: Keep the screenshot aligned with the latest version [screenshot-latest]

In cases where the screenshot is rather conceptually demonstrating a capability, it's fine not to version it.

For example, versioning the screenshot on the [Dashboards](https://www.elastic.co/docs/explore-analyze/dashboards) parent page would not add tremendous value unless the capability drastically evolves.

## Multiple adjacent block elements vary [multiple-block]
### Multiple adjacent block elements vary [multiple-block]

### Solution A: Use applies switch tabs [multiple-block-tabs]
#### Solution A: Use applies switch tabs [multiple-block-tabs]

**When to use applies switch tabs**:
* When the content is structurally similar but differs in detail — for example, slightly different instructions, outputs, or paths.
Expand All @@ -627,36 +705,11 @@
% **Example**:
% <image>

### Solution B: Use headings [multiple-block-headings]
#### Solution B: Use headings [multiple-block-headings]

_Work in progress._

% TO DO: Add all sections
% **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+!`
```
::::
:::::
Loading
Loading