Strategy for "Applies to" badges

[KOTungseth]

Description

We're aligning on a strategy for how documentation communicates minor version and deployment type applicability using the Applies to badges.

The goal is to ensure that users can understand exactly what version and deployment type the content applies to, even though the documentation always shows the latest released content.

To support this, the documentation renders applies_to badges at the page and section levels. These badges indicate lifecycle status (e.g. ga, beta, preview, discontinued) and applicable version(s) for the stack (and orchestrators?), and deployment types (including serverless).

Requirements

• Every documentation page must specify Elastic Stack and Serverless.

• Badges must apply to the paragraph level (not sentence/word level).

• Granular examples for word- and sentence-level differences should be developed and communicated to teams.

• Linting is required in Elastic Docs v3 to ensure authors follow page-level badge rules.

Open questions

• What should the page-level applies_to badge say when the page contains content for multiple Elastic Stack versions? For example, A page is broadly accurate for Elastic Stack 9.0, but a section or paragraph applies only to 9.2.0. Do we display the page-level badge as ga 9.0 or ga 9.2? Or do we omit the version?

• How can users quickly identify which minor version-specific content appears on a page?

• Should we include page-level metadata summaries (e.g. "This page includes content for 9.0–9.2")?

Next steps

• Align on rules and behavior for mixed-version content on a single page

• Define linting rules and required applies_to metadata for new content

• Create examples for:

  • Page-level only
  • Section-level differences
  • Inline {applies_to} use cases
  • Document edge cases and provide fallback behavior

• Define structure for post-processing and metadata tagging in search/indexing

• Update Documenting versions and deployment types for authoring documentation, then communicate

[theletterf]

I've been collecting some thoughts around the usage of applies_to attributes. I'll summarize them here.

Defaults and fallbacks are needed

The existing system already handles granularity very well (see #inline-applies-to), but it requires explicitly stating and nesting lots of versions in the frontmatter, with no known default behavior.

An alternative could be leveraging version definitions in a centralized place and then use this to define both the default rendering behaviors and a simpler approach to frontmatter and inlining.

Essential information

At any point, users should be able to gather the following information from any document:

• To which stacks does it apply.
• What’s the minimum version of the stack supported.
• What’s the status of the feature (Beta, Experimental, etc.)

Versions.yml file

There could be a version.yml file, as I explained in our last call, that would hold the general metadata about versions that could be used for default behaviors. It would also include allowed statuses and deployment types, which would be useful for validation and reference.

# versions.yml - Defines the stateful version landscape for the documentation

# List all major.minor stateful versions currently documented and supported.
# Order from oldest to newest is recommended.
supported_stateful_versions:
  - '9.0'
  - '9.1'
  - '9.2'
  - '9.3' # Beta

# Define the absolute earliest stateful version these docs apply to.
min_supported_stateful_version: '9.0'

# Define the latest generally available stateful version.
latest_stateful_version: '9.2'

# Optional: Define which stateful version view is shown by default
default_stateful_version: '9.0'

allowed_statuses: 
   - beta
   - technical_preview
   - experimental
   - coming_soon

allowed_deployment_types: 
   - serverless
   - stateful 
   - eck
   - ess
   - ece
   - self-managed

We could then use a simplified YAML frontmatter to tag what applies to the document. For example:

---
applies_to: 
 status: beta                 # Optional
 deployment_types:
   - stateful
   - eck
 min_stateful_version: 9.1    # Optional
 deprecated_in_stateful: 9.7  # Optional
---

• By default, documents without the applies_to block or a deployment_types parameter could be assumed to work with all deployment types and will be labeled as such in the frontend.

• The deployment_types parameter handles the exceptions. If only stateful is defined, then the page isn’t labeled as serverless compatible, and vice versa. Or we could assume all docs are Serverless unless deployment types are specified and serverless is not among them.

• When content applies to all types but only starting from a stateful version, it could bear a min_stateful_version attribute. This would be rendered as “9.1 and higher” or even a list of all supported versions. Otherwise, it’s assumed to work starting from the default supported minimum, as defined in the versions.yml file.

• Optionally, one could define the status of the whole doc as “beta”, “preview”, “ga”, etc. The allowed statuses would also be described in the versions.yml file. Files with certain statuses could be selectively excluded from the search, or properly tagged in results.

In-line labeling only for sections

Section and in-line tagging would use the same fields and draw from the same centralized versions file. Section labels could be rendered in the table of contents of the doc.

An example for sections would be:

```{yaml} applies_to 
status: experimental
min_stateful_version: 9.3
deployment_types: ['stateful']�```

Applies to badges would only apply to sections, not to paragraphs, sentences, or words. For those, we would use good old text.

The first version inside a doc wins

As an additional fallback mechanism, we could mandate that, if a document lacks a stateful version at page level, the lowest version used in a section will be used as the minimum version for the entire doc.

Frontmatter validation

We need mechanisms to validate the frontmatter at build. For example, using somethings like https://github.com/JulianCataldo/remark-lint-frontmatter-schema.

[florent-leborgne]

Relates to this discussion as well: elastic/docs-builder#402

[shainaraskas]

Every documentation page must specify Elastic Stack 9.0 and Serverless

stack is not relevant to all pages. e.g. pages where functionality is specific to the orchestrator (example)

"stack 9" implies to me that a feature is available to all contexts where elastic stack can be run. however, in some cases, functionality available in vanilla ES is overridden by the orchestrator, so labeling it "stack 9" would send the wrong message. see cluster-level security and specific topics like tls encryption for a good example of how this gets complicated

[florent-leborgne]

Capturing some additional thoughts after yesterday's meeting:

• The strategy should address the usage of the "unavailable" status. What are the cases where it's useful. (This or related questions already came a few times, especially from support). I think this is at least very useful in deployment type-related docs.
• Still about status, we must be unambiguous about every version-related changes needing a version tag (added 9.1, etc.) for each new minor (unless we go for a different strategy than "this page covers all versions"). That is especially important as teams are already working on 9.1.

[KOTungseth]

Before we move forward with how we display versions, we need to address:

• The broken .co search: Now that Docs are organized by user goal instead of products, users are struggling to find product-specific pages.
• Baseline applies to badges at the page level: We need to add Elastic Stack, Serverless, Elastic Cloud Hosted, ECE, and ECK badges to all Docs pages where the badges apply.

Here is what I propose:

1. The majority of /docs pages include mapped /guide pages in the frontmatter, which tell us the products that apply to the /docs pages. To improve the .co search experience, we'll add product names to the frontmatter.
2. For products listed in the frontmatter that are part of the Elastic Stack, we'll add the Elastic Stack badge.
3. For /docs pages that include mapped:
   • /guide/serverless/ pages, we'll add the Serverless badge
   • /guide/cloud/ pages, we'll add the Elastic Cloud Hosted badge
   • /guide/cloud-enterprise/ pages, we'll add the ECE badge
   • /guide/cloud-on-k8s/ pages, we'll add the ECK badge

[shainaraskas]

Baseline applies to badges at the page level: We need to add Elastic Stack, Serverless, Elastic Cloud Hosted, ECE, and ECK badges to all Docs pages where the badges apply.

Elastic Stack is not synonymous with self-managed (vanilla elasticsearch). In a deployment context, or where features are augmented/overridden by deployment type, we need to use self-managed instead of Elastic Stack.

we need to be very careful about the pages in the elasticsearch book to handle for this. likely, the largest impact is to troubleshooting and deploy + manage, but the blast radius might be larger than that.

[florent-leborgne]

That's right, pages in our new IA are affected by at least 2 dimensions that are surfacing through the existing applies_to tags:

• "Which Stack interface (UI/API) version is this page relevant for": It can be stack (as for the versioned Elastic Stack) or serverless with our current possible values. This dimension is useful on /solutions and /explore-analyze docs particularly, and probably also for many /manage-data pages.
• "Which Stack deployment type is this page relevant for": It can be self, cloud hosted, serverless, ece, eck. As in "This page specifically talks about administering your {deployment_type} environment" or "This page talks about managing the XYZ Elastic Stack feature specifically when it's deployed on a {deployment_type} environment". This dimension is useful on /deploy-manage particularly. On the other hand, it's not as relevant to display this dimension on /solutions and /explore-analyze, they all apply in most cases, but they do not represent THE key dimension for understanding/reading the document (We could still display them though?)

Pages from other docs nodes (/troubleshooting, /release-notes, /reference) would generally use one or both of these dimensions, on a case by case basis, since they contain more heterogenous docs.