Skip to content

Adds cumulative docs contribution overview #1324

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.

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

Merged
merged 11 commits into from
Jun 16, 2025
25 changes: 24 additions & 1 deletion docs/contribute/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,29 @@ To contribute to earlier versions of the Elastic Stack, you must work with our [
* For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md)
* For **complex or multi-page updates** --> [Contribute locally](locally.md)

Starting with Elastic Stack version 9.0, ECE 4.0, and ECK 3.0, a new set of docs is no longer published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content using a [cumulative approach](#cumulative-docs).

#### Write cumulative documentation [#cumulative-docs]

Cumulative documentation means that one page can cover multiple product versions, deployment types, and release stages. Instead of creating separate pages for each release, we update the same page with version-specific details.

This helps readers understand which parts of the content apply to their own ecosystem and product versions, without needing to switch between different versions of a page.

Following this approach, information for supported versions must not be removed unless it was never accurate. Instead, refactor the content to improve clarity or to include details for other products, deployment types, or versions.

In order to achieve this, the markdown source files integrate a **tagging system** meant to identify:

* Which Elastic products and deployment models the content applies to.
* When a feature goes into a new state as compared to the established base version.

This [tagging system](#applies-to) is mandatory for all of the public-facing documentation.

##### The `applies_to` tag [#applies-to]

Use the [`applies_to`](../syntax/applies.md) tag to indicate which versions, deployment types, or release stages each part of the content is relevant to.

You must always use the `applies_to` tag at the [page](../syntax/applies.md#page-annotations) level. Optionally, you can also use it at the [section](../syntax/applies.md#sections) or [inline](../syntax/applies.md#inline-applies-to) level if certain parts of the content apply only to specific versions, deployment types, or release stages.
Copy link
Contributor

@leemthompo leemthompo May 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@charlotte-hoblik this should be emphasized in the applies_to reference itself too: it should be hyper clear that page-level applies_to are mandatory, and how we use the lower-level ones to write [cumulative docs](linky link)


## Report a bug

* It's a **documentation** problem --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md)
Expand All @@ -36,4 +59,4 @@ To contribute to earlier versions of the Elastic Stack, you must work with our [

## Work on docs-builder

That sounds great! See [development](../development/index.md) to learn how to contribute to our documentation build system.
That sounds great! See [development](../development/index.md) to learn how to contribute to our documentation build system.
Loading