Write cumulative documentation

In elastic.co/docs (Docs V3) we write docs cumulatively. This means that in our Markdown-based docs, there is no longer a new documentation set published with every minor release: the same page stays valid over time and shows version-related evolutions.

With cumulative documentation, when a user arrives in our documentation from an outside source, they land on a page that is a single source of truth. This means it will be more likely that the page they land on contains content that applies to them regardless of which version or deployment type they are using.

Users can then compare and contrast differences on a single page to understand what is available to them and explore the ways certain offerings might improve their experience.

×

With cumulative documentation, there is a single "source of truth" for each feature, which helps us to maintain consistency, accuracy, and maintainability of our documentation over time, and avoids "drift" between multiple similar sets of documentation.

As new minor versions are released, we want users to be able to distinguish which content applies to their own ecosystem and product versions without having to switch between different versions of a page.

This extends to deprecations and removals: No information should be removed for supported product versions, unless it was never accurate. It can be refactored to improve clarity and flow, or to accommodate information for additional products, deployment types, and versions as needed.

To achieve this, the Markdown source files integrate a tagging system.

Every page should include page-level applies_to tags to indicate which product or deployment type the content applies to. This is mandatory for every page.

You should also generally tag content when:

• Functionality is added
• Functionality changes state, like going from beta to GA
• Availability varies, like being available in Elastic Cloud Enterprise but not in Elastic Cloud Hosted

For detailed guidance on contributing to cumulative docs, refer to Cumulative docs guidelines.

You generally do not need to tag:

• Content-only changes, like fixing typos
• Every paragraph/section when the applicability has been established earlier on the page
• Unversioned products, where all users are always on the latest version, when adding features that are generally available

We have a central version config called versions.yml, which tracks the latest released versions of our products. It also tracks the earliest version of each product documented in the Docs V3 system (the earliest available on elastic.co/docs).

This central version config is used in certain inline version variables and drives our dynamic rendering logic, which allows us to label documentation related to unreleased versions as planned, continuously release documentation, and document our Serverless and Elastic Stack offerings in one place.

applies_to tags are rendered as badges in the documentation output. They reproduce the "key + lifecycle status + version" indicated in the content sources.

Specifically for versioned products, badges will display differently when the applies_to key specifies a product version that has not been released to our customers yet.

• Planned (if the lifecycle is preview, beta, or ga)

  Example: Stack Planned

• Deprecation planned (if the lifecycle is deprecated)

  Example: Stack Deprecation planned

• Removal planned (if the lifecycle is removed)

  Example: Stack Removal planned

This is computed at build time (there is a docs build every 30 minutes). The documentation team tracks and maintains released versions for these products centrally in versions.yml. When multiple lifecycle statuses and versions are specified in the sources, several badges are shown.

Read more about how to tag content in:

• Cumulative docs guidelines: Review more detailed guidance on when to tag content.
• Badge usage and placement: Learn how to integrate applies_to badges into docs content.
• Example scenarios: Browse common scenarios you might run into as a docs contributor that require different approaches to labeling cumulative docs.
• applies_to syntax guide: Reference all valid values and syntax patterns available in applies_to.