From 6815f45a7b311d3473caf9071281b62ad65bdf0e Mon Sep 17 00:00:00 2001 From: kosabogi Date: Fri, 30 May 2025 11:45:56 +0200 Subject: [PATCH 1/7] Add cumulative docs contribution guidance --- docs/contribute/index.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 0af35e1c1..084163f7e 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -24,6 +24,20 @@ 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 and later, 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] + +:::{note} +This section only applies to Elastic Stack version 9.0 docs and later. +::: + +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. + +Use the `applies_to` tag to indicate which versions, deployment types, or release stages each part of the content is relevant to. Refer to the [Applies to syntax guide](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/applies) for more details. + +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#sections) or [inline](../syntax/applies#inline-applies-to) level if certain parts of the content apply only to specific versions, deployment types, or release stages. + ## 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) @@ -36,4 +50,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. \ No newline at end of file From 8dc9d7553807f92fc8ddaa783c85fb9cd0ec6066 Mon Sep 17 00:00:00 2001 From: kosabogi Date: Fri, 30 May 2025 11:51:46 +0200 Subject: [PATCH 2/7] Fixes links --- docs/contribute/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 084163f7e..45b067b40 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -36,7 +36,7 @@ Cumulative documentation means that one page can cover multiple product versions Use the `applies_to` tag to indicate which versions, deployment types, or release stages each part of the content is relevant to. Refer to the [Applies to syntax guide](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/applies) for more details. -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#sections) or [inline](../syntax/applies#inline-applies-to) level if certain parts of the content apply only to specific versions, deployment types, or release stages. +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. ## Report a bug From f651d38249b2c3381f2d4636b45880a0c2fa68ec Mon Sep 17 00:00:00 2001 From: kosabogi <105062005+kosabogi@users.noreply.github.com> Date: Fri, 30 May 2025 12:25:06 +0200 Subject: [PATCH 3/7] Update docs/contribute/index.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/contribute/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 45b067b40..d91786a60 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -34,7 +34,7 @@ This section only applies to Elastic Stack version 9.0 docs and later. 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. -Use the `applies_to` tag to indicate which versions, deployment types, or release stages each part of the content is relevant to. Refer to the [Applies to syntax guide](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/applies) for more details. +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. From 898d1ca62d7e3b50b4b1fe2720936a0c46088087 Mon Sep 17 00:00:00 2001 From: kosabogi <105062005+kosabogi@users.noreply.github.com> Date: Fri, 30 May 2025 12:25:24 +0200 Subject: [PATCH 4/7] Update docs/contribute/index.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/contribute/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index d91786a60..7e676aed3 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -24,7 +24,7 @@ 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 and later, 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). +Starting with Elastic Stack version 9.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] From 78700fe40430ee594876fe0caa55a6bcbac409ea Mon Sep 17 00:00:00 2001 From: kosabogi Date: Fri, 30 May 2025 12:31:23 +0200 Subject: [PATCH 5/7] Nesting section and deleting note --- docs/contribute/index.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 7e676aed3..a5030f2c4 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -26,11 +26,7 @@ To contribute to earlier versions of the Elastic Stack, you must work with our [ Starting with Elastic Stack version 9.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] - -:::{note} -This section only applies to Elastic Stack version 9.0 docs and later. -::: +#### 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. From dc819fc964bccc0a58135f04b438e148df0fc4af Mon Sep 17 00:00:00 2001 From: kosabogi Date: Fri, 30 May 2025 13:02:59 +0200 Subject: [PATCH 6/7] Adds more information --- docs/contribute/index.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index a5030f2c4..ebcf260ac 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -30,6 +30,19 @@ Starting with Elastic Stack version 9.0, a new set of docs is no longer publishe 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. From f8f9d0b7ca77473915d3e4f3cdcde10e4bcf1b7e Mon Sep 17 00:00:00 2001 From: kosabogi <105062005+kosabogi@users.noreply.github.com> Date: Mon, 16 Jun 2025 11:39:57 +0200 Subject: [PATCH 7/7] Update docs/contribute/index.md Co-authored-by: florent-leborgne --- docs/contribute/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index ebcf260ac..61076f1ac 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -24,7 +24,7 @@ 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, 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). +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]