Add best practices for applies_to (#1614)

* initial outline

* fix links

* reorg

* continue building out content

* apply suggestions from code review

Co-authored-by: Brandon Morelli <[email protected]>

* address some feedback from @bmorelli's first round of review

* fix link

* reorg

* deduplicate

* finish building out badge placement page

* clean up guidelines and examples

* clarify

* add more examples

* add more examples

* add redirects

* apply suggestions from code review

Co-authored-by: florent-leborgne <[email protected]>

* clarify title

* address badge placement feedback

* address some feedback on examples

* remove branching strategy ref

Co-authored-by: Liam Thompson <[email protected]>

* shain-ify the guidelines page

Co-authored-by: shainaraskas <[email protected]>

* shain-ify the reference page

Co-authored-by: shainaraskas <[email protected]>

* shain-ify badge placement page

* remove redirect

* try a different redirect

* Update docs/contribute/cumulative-docs/guidelines.md

Co-authored-by: shainaraskas <[email protected]>

* revert changes to docs/syntax/_snippets/page-level-applies-examples.md

* clean up general guidelines section

* clean up section on removed features

* add information on badge usage

* soften table guidelines

* soften guideline on badges taking up space

---------

Co-authored-by: Brandon Morelli <[email protected]>
Co-authored-by: florent-leborgne <[email protected]>
Co-authored-by: Liam Thompson <[email protected]>
Co-authored-by: shainaraskas <[email protected]>

Author: 5 people

docs/_docset.yml

@@ -36,7 +36,13 @@ toc:
       - file: on-the-web.md
       - file: move.md
       - file: redirects.md
-      - file: cumulative-docs.md
+      - folder: cumulative-docs
+        children:
+          - file: index.md
+          - file: guidelines.md
+          - file: badge-placement.md
+          - file: example-scenarios.md
+          - file: reference.md
       - file: branching-strategy.md
       - file: add-repo.md
       - file: release-new-version.md
@@ -112,10 +118,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)
@@ -146,7 +148,7 @@ toc:
       - folder: deeply-nested
         children:
           - file: index.md
-          - file: foo.md 
+          - file: foo.md
           - file: bar.md
           - folder: baz
             children:

docs/_redirects.yml

@@ -21,4 +21,10 @@ redirects:
           "yy": "bb"
   'testing/redirects/third-page.md':
     anchors:
-      'removed-anchor':
+      'removed-anchor':
+  # Related to https://github.com/elastic/docs-builder/pull/1614
+  'docs/contribute/cumulative-docs.md': 'contribute/cumulative-docs/index.md'
+  'docs/versions/content-patterns.md': 'contribute/cumulative-docs/example-scenarios.md'
+  'docs/versions/index.md': 'contribute/cumulative-docs/index.md'
+  # I shouldn't need to do this should I?
+  'docs/versions/_snippets/content-patterns-list.md': 'contribute/cumulative-docs/index.md'

docs/_snippets/applies_to-key.md

@@ -0,0 +1,36 @@
+`applies_to` accepts the following keys in this structure:
+
+* `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).
+* `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).
+  * `ece`: Applies to [Elastic Cloud Enterprise](https://www.elastic.co/docs/deploy-manage/deploy/cloud-enterprise) deployments.
+  * `eck`: Applies to [Elastic Cloud on Kubernetes](https://www.elastic.co/docs/deploy-manage/deploy/cloud-on-k8s) deployments.
+  * `self`: Applies to [self-managed](https://www.elastic.co/docs/deploy-manage/deploy/self-managed) deployments.
+  * `ess`: Applies to [Elastic Cloud Hosted](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/cloud-hosted) deployments.
+* `product`: Applies to a specific product that uses a unique versioning scheme (e.g. not `stack`, `ece`, `eck`).
+  * `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).
+  * `curator`: Applies to [Elasticsearch Curator](https://www.elastic.co/docs/reference/elasticsearch/curator) (Curator).
+  * `ecctl`: Applies to [Elastic cloud control](https://www.elastic.co/docs/reference/ecctl) (ECCTL).
+  * `edot_android`: Applies to the [Elastic Distribution of OpenTelemetry Android](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/android/) (EDOT Android).
+  * `edot_cf_aws`: Applies to the [Elastic Distribution of OpenTelemetry Cloud Forwarder](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/) (EDOT Cloud Forwarder).
+  * `edot_collector`: Applies to the [Elastic Distribution of OpenTelemetry Collector](https://www.elastic.co/docs/reference/opentelemetry/edot-collector/) (EDOT Collector).
+  * `edot_dotnet`: Applies to the [Elastic Distribution of OpenTelemetry .NET](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/dotnet/) (EDOT .NET).
+  * `edot_ios`: Applies to the [Elastic Distribution of OpenTelemetry iOS](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/ios/) (EDOT iOS).
+  * `edot_java`: Applies to the [Elastic Distribution of OpenTelemetry Java](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/java/) (EDOT Java).
+  * `edot_node`: Applies to the [Elastic Distribution of OpenTelemetry Node.js](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/nodejs/) (EDOT Node.js).
+  * `edot_php`: Applies to the [Elastic Distribution of OpenTelemetry PHP](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/php/) (EDOT PHP).
+  * `edot_python`: Applies to the [Elastic Distribution of OpenTelemetry Python](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/python/) (EDOT Python).
+  
+:::{note}
+The `products` key and its subkeys are used to indicate feature availability and applicability. The similarly named [`products` frontmatter field](/syntax/frontmatter.md#products) is used to drive elastic.co search filters.
+:::

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
 ```