[work in progress!!] Add best practices for applies_to

docs/_docset.yml

@@ -34,7 +34,12 @@ toc:
       - file: on-the-web.md
       - file: move.md
       - file: redirects.md
-      - file: cumulative-docs.md
+      - folder: cumulative-docs
+        children:
+          - file: index.md
+          - file: reference.md
+          - file: best-practices.md
+          - file: content-patterns.md
       - file: branching-strategy.md
       - file: add-repo.md
       - file: release-new-version.md
@@ -110,10 +115,6 @@ toc:
       - file: tabs.md
       - file: tagged_regions.md
       - file: titles.md
-  - folder: versions
-    children:
-      - file: index.md
-      - file: content-patterns.md
   # nested TOCs are only allowed from docset.yml by default
   # to prevent them from being nested deeply arbitrarily
   # use max_toc_depth to allow deeper nesting (Expert mode, consult with docs team)
@@ -144,7 +145,7 @@ toc:
       - folder: deeply-nested
         children:
           - file: index.md
-          - file: foo.md 
+          - file: foo.md
           - file: bar.md
           - folder: baz
             children:

docs/_snippets/applies_to-key.md

@@ -0,0 +1,36 @@
+`applies_to` accepts the following keys in this structure:
+
+* `stack`: Applies to the [Elastic Stack](https://www.elastic.co/docs/get-started/the-stack) including any Elastic Stack components.
+* `deployment`: Applies to some deployment type(s).
+  * `eck`: Applies to [Elastic Cloud on Kubernetes](https://www.elastic.co/docs/deploy-manage/deploy/cloud-on-k8s) deployments.
+  * `ech`: Applies to [Elastic Cloud Hosted](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/cloud-hosted) deployments.
+  * `ece`: Applies to [Elastic Cloud Enterprise](https://www.elastic.co/docs/deploy-manage/deploy/cloud-enterprise) deployments.
+  * `self`: Applies to [self-managed](https://www.elastic.co/docs/deploy-manage/deploy/self-managed) deployments.
+  * `ess`: Applies to Elasticsearch Service deployments. {applies_to}`product: deprecated`
+    :::{note}
+    Use `ech` instead.
+    :::
+* `serverless`: Applies to [Elastic Cloud Serverless](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/serverless).
+  * `security`: Applies to Serverless [security projects](https://www.elastic.co/docs/solutions/security/get-started/create-security-project).
+  * `elasticsearch`: Applies to Serverless [search projects](https://www.elastic.co/docs/solutions/search/serverless-elasticsearch-get-started).
+  * `observability`: Applies to Serverless [observability projects](https://www.elastic.co/docs/solutions/observability/get-started).
+* `product`: Applies to a specific product.
+  * `ecctl`: Applies to [Elastic cloud control](https://www.elastic.co/docs/reference/ecctl).
+  * `curator`: Applies to [Elasticsearch Curator](https://www.elastic.co/docs/reference/elasticsearch/curator).
+  * `apm_agent_dotnet`: Applies to the [Elastic APM .NET agent](https://www.elastic.co/docs/reference/apm/agents/dotnet).
+  * `apm_agent_go`: Applies to the [Elastic APM Go agent](https://www.elastic.co/docs/reference/apm/agents/go).
+  * `apm_agent_java`: Applies to the [Elastic APM Java agent](https://www.elastic.co/docs/reference/apm/agents/java).
+  * `apm_agent_node`: Applies to the [Elastic APM Node.js agent](https://www.elastic.co/docs/reference/apm/agents/nodejs).
+  * `apm_agent_php`: Applies to the [Elastic APM PHP agent](https://www.elastic.co/docs/reference/apm/agents/php).
+  * `apm_agent_python`: Applies to the [Elastic APM Python agent](https://www.elastic.co/docs/reference/apm/agents/python).
+  * `apm_agent_ruby`: Applies to the [Elastic APM Ruby agent](https://www.elastic.co/docs/reference/apm/agents/ruby).
+  * `apm_agent_rum`: Applies to the [APM RUM JavaScript agent](https://www.elastic.co/docs/reference/apm/agents/rum-js).
+  * `edot_collector`: Applies to the [Elastic Distribution of OpenTelemetry Collector](https://www.elastic.co/docs/reference/opentelemetry/edot-collector/).
+  * `edot_ios`: Applies to the [Elastic Distribution of OpenTelemetry iOS](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/ios/).
+  * `edot_android`: Applies to the [Elastic Distribution of OpenTelemetry Android](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/android/).
+  * `edot_dotnet`: Applies to the [Elastic Distribution of OpenTelemetry .NET](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/dotnet/).
+  * `edot_java`: Applies to the [Elastic Distribution of OpenTelemetry Java](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/java/).
+  * `edot_node`: Applies to the [Elastic Distribution of OpenTelemetry Node.js](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/nodejs/).
+  * `edot_php`: Applies to the [Elastic Distribution of OpenTelemetry PHP](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/php/).
+  * `edot_python`: Applies to the [Elastic Distribution of OpenTelemetry Python](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/python/).
+  * `edot_cf_aws`: Applies to the [Elastic Distribution of OpenTelemetry Cloud Forwarder](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/).

docs/_snippets/applies_to-lifecycle.md

@@ -0,0 +1,8 @@
+`applies_to` accepts the following lifecycle states:
+
+* `preview`
+* `beta`
+* `ga`
+* `deprecated`
+* `removed`
+* `unavailable`

docs/_snippets/applies_to-version.md

@@ -0,0 +1,9 @@
+`applies_to` accepts the following version formats:
+
+* `Major.Minor`
+* `Major.Minor.Patch`
+
+:::{note}
+Regardless of the version format used in the source file,
+the version number will always be rendered in the `Major.Minor.Patch` format.
+:::

docs/configure/site/versions.md

@@ -16,4 +16,4 @@ Versions set in this file are surfaced to the user via `applies_to` tags.
 :::{include} /contribute/_snippets/tag-processing.md
 :::
 
-See [](../../contribute/cumulative-docs.md) for more information.
+See [](/contribute/cumulative-docs/index.md) for more information.

docs/contribute/_snippets/docs-intro.md

@@ -2,4 +2,4 @@ elastic.co/docs uses our new build system, also known as "Docs V3", which uses a
 
 Docs for {{stack}} 9.x, {{ece}} 4.x, and {{eck}} 3.x can all be found on this site. All unversioned products, such as {{ech}} and {{serverless-full}}, are also documented on elastic.co/docs.
 
-This documentation is **cumulative**. This means that a new set of docs is not published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content. [Learn how to write cumulative documentation](/contribute/cumulative-docs.md).
+This documentation is **cumulative**. This means that a new set of docs is not published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content. [Learn how to write cumulative documentation](/contribute/cumulative-docs/index.md).

docs/contribute/add-repo.md

@@ -17,7 +17,7 @@ The new docs repository needs to satisfy these requirements:
 
 Follow these instructions to add a new repository to the docs.
 
-:::::{stepper}   
+:::::{stepper}
 
 ::::{step} Add the repo to docs-infra
 
@@ -55,7 +55,7 @@ references:
 ```
 
 :::{tip}
-In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [branching strategy](branching-strategy.md). You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
+In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [branching strategy](/contribute/branching-strategy.md). You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
 :::
 
 Then, edit the [`navigation.yml`](https://github.com/elastic/docs-builder/blob/main/config/navigation.yml) file to add the repository to the navigation. Refer to [navigation.yml](../configure/site/navigation.md) for more information.
@@ -98,5 +98,5 @@ For example, to add version 13.5 of yadda-docs:
 For a more comfortable local `docs-builder` experience, add the following line to the `.gitignore` file of the repo:
 
 ```
-docs/.artifacts 
+docs/.artifacts
 ```