diff --git a/docs/_docset.yml b/docs/_docset.yml index a09f0def2..355a628fc 100644 --- a/docs/_docset.yml +++ b/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: diff --git a/docs/_snippets/applies_to-key.md b/docs/_snippets/applies_to-key.md new file mode 100644 index 000000000..3e58c62f8 --- /dev/null +++ b/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/). diff --git a/docs/_snippets/applies_to-lifecycle.md b/docs/_snippets/applies_to-lifecycle.md new file mode 100644 index 000000000..439613d3c --- /dev/null +++ b/docs/_snippets/applies_to-lifecycle.md @@ -0,0 +1,8 @@ +`applies_to` accepts the following lifecycle states: + +* `preview` +* `beta` +* `ga` +* `deprecated` +* `removed` +* `unavailable` \ No newline at end of file diff --git a/docs/_snippets/applies_to-version.md b/docs/_snippets/applies_to-version.md new file mode 100644 index 000000000..64d72cd7f --- /dev/null +++ b/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. +::: diff --git a/docs/configure/site/versions.md b/docs/configure/site/versions.md index 53121f1cc..f307a3bdc 100644 --- a/docs/configure/site/versions.md +++ b/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. \ No newline at end of file +See [](/contribute/cumulative-docs/index.md) for more information. \ No newline at end of file diff --git a/docs/contribute/_snippets/docs-intro.md b/docs/contribute/_snippets/docs-intro.md index da6162298..ab21f4c68 100644 --- a/docs/contribute/_snippets/docs-intro.md +++ b/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). \ No newline at end of file +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). \ No newline at end of file diff --git a/docs/contribute/add-repo.md b/docs/contribute/add-repo.md index b5d34a59f..255862acd 100644 --- a/docs/contribute/add-repo.md +++ b/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 ``` diff --git a/docs/contribute/branching-strategy.md b/docs/contribute/branching-strategy.md index 6f045d528..c68932826 100644 --- a/docs/contribute/branching-strategy.md +++ b/docs/contribute/branching-strategy.md @@ -4,7 +4,7 @@ navigation_title: Choose a branching strategy # Choose the docs branching strategy for a repository -With Docs V3 (elastic.co/docs), a single branch is published per repository. This branch is set to `main` by default. This is known as the continuous deployment branching strategy. However, it is possible to instead publish a different branch, also known as the tagged branching strategy. +With Docs V3 (elastic.co/docs), a single branch is published per repository. This branch is set to `main` by default. This is known as the continuous deployment branching strategy. However, it is possible to instead publish a different branch, also known as the tagged branching strategy. On this page, you'll learn how to choose the right branching strategy for your repository, and how to change the branching strategy. You'll also learn about the workflows for working with each branching strategy. @@ -12,22 +12,22 @@ On this page, you'll learn how to choose the right branching strategy for your r The main reasons for this choice are: -* With Docs V3, there is no longer a different version of each page for each minor release. Instead, the same page [covers all versions](cumulative-docs.md), and any changes are indicated throughout the content. +* With Docs V3, there is no longer a different version of each page for each minor release. Instead, the same page [covers all versions](/contribute/cumulative-docs/index.md), and any changes are indicated throughout the content. * More and more products are released from `main` branches, making these branches the most up to date at any given time. This is especially true for {{serverless-full}} and {{ecloud}}. - + ## Why would we want to publish a different branch instead? Publishing from the main branch isn’t the best option for all repositories. -* `main` can contain code and docs for unreleased versions that we don’t want to publish yet. +* `main` can contain code and docs for unreleased versions that we don’t want to publish yet. * The versioning scheme and release cadence of the product associated with a repository can vary, and it can be inconsistent to have the docs associated with a certain version live in a different branch than the code. If you choose this publication model for your repository AND that repository includes {{serverless-short}} or {{ecloud}} documentation, you will need to make sure that {{serverless-short}}- and {{ecloud}}-related changes are also backported to the branch that is publishing to the public docs site. -You **don't** need to change your branching strategy to enable writing docs about future versions. Review the [continuous deployment workflow](#workflow-1-default-continuous-deployment) and [](cumulative-docs.md) to learn more. +You **don't** need to change your branching strategy to enable writing docs about future versions. Review the [continuous deployment workflow](#workflow-1-default-continuous-deployment) and [](/contribute/cumulative-docs/index.md) to learn more. -Note that regardless of the publication branch that is set, the documentation must still flag all changes introduced so far since the last major release. This is NOT an alternative to [writing docs cumulatively](cumulative-docs.md). +Note that regardless of the publication branch that is set, the documentation must still flag all changes introduced so far since the last major release. This is NOT an alternative to [writing docs cumulatively](/contribute/cumulative-docs/index.md). ## How to change the published branch @@ -39,10 +39,10 @@ After it has been established that a repository should publish from a version br 1. [Add new triggers to the `docs-build` CI integration](/configure/content-sources.md#ci-configuration). Merge these changes to `main` or `master` and the intended version branches. 2. Open a PR to trigger the CI integration and confirm that the docs build. -3. Open a PR updating the [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml): - * Specify which is the `current` branch for the repository. This branch is the branch from which docs are deployed to production at [elastic.co/docs](http://elastic.co/docs). - * Specify which is the `next` branch for the repository. The branch defined as `next` publishes docs internally to [staging-website.elastic.co/docs](http://staging-website.elastic.co/docs) - * Setting this branch to the next version branch in line is a good practice to preview docs change for an upcoming version. +3. Open a PR updating the [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml): + * Specify which is the `current` branch for the repository. This branch is the branch from which docs are deployed to production at [elastic.co/docs](http://elastic.co/docs). + * Specify which is the `next` branch for the repository. The branch defined as `next` publishes docs internally to [staging-website.elastic.co/docs](http://staging-website.elastic.co/docs) + * Setting this branch to the next version branch in line is a good practice to preview docs change for an upcoming version. * Otherwise, keeping it set to `main` is also an option since this is where the content is initially developed and merged. This is the default. 4. In the assembler PR, add the `ci` label. After CI runs, confirm that the intended version branches are publishing to the link service. When links are being published as intended, they can be found at the following URL, where `repo` is your repo name and `branch` is your newly configured branch: @@ -58,12 +58,12 @@ After these steps are completed, the docs engineering team needs to release a ne When you publish from specific version branches, you need to bump the version branch as part of the release process. -Add an action as part of that repo’s release process for the release manager to update this same assembler file and bump the `current` branch with each release, as appropriate. The `next` branch also needs to be bumped if it is not set to `main`. +Add an action as part of that repo’s release process for the release manager to update this same assembler file and bump the `current` branch with each release, as appropriate. The `next` branch also needs to be bumped if it is not set to `main`. When these releases happen, create a PR against the [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) that defines the new `current` branch, to merge on release day. :::{tip} -Regardless of the branching strategy, you also need to update the current version in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml) as part of your release process. This version number is used in documentation variables and drives our [dynamic version badge logic](/contribute/cumulative-docs.md#how-do-these-tags-behave-in-the-output). +Regardless of the branching strategy, you also need to update the current version in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml) as part of your release process. This version number is used in documentation variables and drives our [dynamic version badge logic](/contribute/cumulative-docs/index.md#how-do-these-tags-behave-in-the-output). ::: @@ -77,7 +77,7 @@ Initiate the changes by opening a PR against the `main` branch of the repo. ### How to write those changes [write-changes-cd] -In elastic.co/docs (Docs V3), we [write docs cumulatively](cumulative-docs.md) regardless of the branching strategy selected. +In elastic.co/docs (Docs V3), we [write docs cumulatively](/contribute/cumulative-docs/index.md) regardless of the branching strategy selected. ### Merging and backporting [merge-backport-cd] @@ -86,8 +86,8 @@ When a repo publishes docs from its `main` branch, any merged changes are publis | | Case | Approach | | --- | --- | --- | | 1 | You are documenting changes for an unversioned product (typically Serverless or Elastic Cloud), and the changes should only go live when the corresponding code or feature is available to users. | The PR should be merged on or after the release date of the feature. | -| 2 | You are documenting changes for a versioned product (any Stack components, ECE, ECK, etc.). | You have the choice between merging the PR as soon as it is approved, or merging it only on release day.

We have an automatic mechanism in place as part of the [cumulative docs strategy](cumulative-docs.md) that will show any changes published before its associated code or feature is available as `Planned`. | -| 3 | You are documenting changes that apply to both versioned and unversioned products (typically a change that is being released for both Serverless and an upcoming Stack release). | The PR should only be merged on or after the release date of the feature in Serverless.

For versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](cumulative-docs.md) that will show any changes published before its associated code or feature is available as `Planned`. | +| 2 | You are documenting changes for a versioned product (any Stack components, ECE, ECK, etc.). | You have the choice between merging the PR as soon as it is approved, or merging it only on release day.

We have an automatic mechanism in place as part of the [cumulative docs strategy](/contribute/cumulative-docs/index.md) that will show any changes published before its associated code or feature is available as `Planned`. | +| 3 | You are documenting changes that apply to both versioned and unversioned products (typically a change that is being released for both Serverless and an upcoming Stack release). | The PR should only be merged on or after the release date of the feature in Serverless.

For versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](/contribute/cumulative-docs/index.md) that will show any changes published before its associated code or feature is available as `Planned`. | When a repo is publishing docs from its `main` branch, no backporting is needed. @@ -97,7 +97,7 @@ If you don’t want to hold on too many PRs to publish on release day, merge the ## Workflow 2: Tagged -Learn how to make updates in the continuous deployment branching strategy, where the repo is publishing docs from a specific version branch. +Learn how to make updates in the continuous deployment branching strategy, where the repo is publishing docs from a specific version branch. ### Where to make docs changes [make-changes-td] @@ -105,7 +105,7 @@ Initiate the changes by opening a PR against the `main` branch of the repo, and ### How to write those changes [write-changes-td] -In elastic.co/docs (Docs V3), we [write docs cumulatively](cumulative-docs.md) regardless of the branching strategy selected. +In elastic.co/docs (Docs V3), we [write docs cumulatively](/contribute/cumulative-docs/index.md) regardless of the branching strategy selected. ### Merging and backporting [merge-backport-td] @@ -116,19 +116,19 @@ The changes must then be backported to their relevant version branches, and no f | | Case | Approach | | --- | --- | --- | | 1 | You are documenting changes for an unversioned product (typically Serverless or Elastic Cloud), the changes should go live when the corresponding code or feature is available to users. | The PR should be backported to the docs `current` branch, and any intermediate version branches that already exist between `current` and `main`. Merge the backport PR for `current` only when you’re sure the corresponding feature is released. | -| 2 | You are documenting changes for a versioned product (any Stack components, ECE, ECK, etc.). | Backport the PR to the relevant version branch and to any intermediate version branch that already exists. The changes will go live whenever these branches become the `current` docs branch.

We have an automatic mechanism in place as part of the [cumulative docs strategy](cumulative-docs.md) that will show any changes published before its associated code or feature is available as `Planned`. | -| 3 | You are documenting changes that apply to both versioned and unversioned products (typically a change that is being released for both Serverless and an upcoming Stack release). | The PR should be backported to the docs `current` branch, and any intermediate version branches that already exist between `current` and `main`. Merge the backport PR for `current` only when you’re sure the corresponding feature is released.

For versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](cumulative-docs.md) that will show any changes published before its associated code or feature is available as `Planned`. | +| 2 | You are documenting changes for a versioned product (any Stack components, ECE, ECK, etc.). | Backport the PR to the relevant version branch and to any intermediate version branch that already exists. The changes will go live whenever these branches become the `current` docs branch.

We have an automatic mechanism in place as part of the [cumulative docs strategy](/contribute/cumulative-docs/index.md) that will show any changes published before its associated code or feature is available as `Planned`. | +| 3 | You are documenting changes that apply to both versioned and unversioned products (typically a change that is being released for both Serverless and an upcoming Stack release). | The PR should be backported to the docs `current` branch, and any intermediate version branches that already exist between `current` and `main`. Merge the backport PR for `current` only when you’re sure the corresponding feature is released.

For versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](/contribute/cumulative-docs/index.md) that will show any changes published before its associated code or feature is available as `Planned`. | #### Example [example-td] For example, in a situation where 9.0, 9.1, and 9.2 are already released, and the 9.3 branch has already been cut: -* The branch set as `current` in the [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) is 9.2. -* The branch set as `next` (where the content development first happens), is `main`. -* 9.4 changes are only done on the `main` branch. -* 9.3 changes are done on the `main` branch and backported to the 9.3 branch. -* 9.1 changes are done on the `main` branch and backported to the 9.3 and 9.2 branches. Since 9.2 is the current docs branch, no need to go further. -* Serverless changes are done on the `main` branch. They are backported to the `current` docs branch and any intermediate branches. In this case: 9.3 and 9.2. +* The branch set as `current` in the [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) is 9.2. +* The branch set as `next` (where the content development first happens), is `main`. +* 9.4 changes are only done on the `main` branch. +* 9.3 changes are done on the `main` branch and backported to the 9.3 branch. +* 9.1 changes are done on the `main` branch and backported to the 9.3 and 9.2 branches. Since 9.2 is the current docs branch, no need to go further. +* Serverless changes are done on the `main` branch. They are backported to the `current` docs branch and any intermediate branches. In this case: 9.3 and 9.2. * Changes not specific to a version are done on the `main` branch and backported to all branches down to the `current` docs branch. In this case: 9.3 and 9.2. :::{note} diff --git a/docs/contribute/cumulative-docs/_snippets/content-patterns-list.md b/docs/contribute/cumulative-docs/_snippets/content-patterns-list.md new file mode 100644 index 000000000..d1c0cc892 --- /dev/null +++ b/docs/contribute/cumulative-docs/_snippets/content-patterns-list.md @@ -0,0 +1,11 @@ +% | Approach | Use case | +% | --- | --- | +% | [Page-level `applies` tags](/versions/content-patterns.md#page-level-applies-tags) | Provide signals that a page applies to the reader. | +% | [Section/heading-level `applies` tags](/versions/content-patterns.md#sectionheading-level-applies-tags) | Provide signals about a section’s scope so a user can choose to read or skip it as needed. | +% | [Tabs](/versions/content-patterns.md#tabs) | Provide two sets of procedures when one or more steps in a process differs between contexts or versions. | +% | [Callouts](/versions/content-patterns.md#callouts) | Draw attention to happy differences and basic clarifications. | +% | [Prose](/versions/content-patterns.md#prose) | - Identify features in a list of features that are exclusive to a specific context, or that were introduced in a specific version
- List differing requirements, limits, and other simple, mirrored facts
- Provide clarifying or secondary information
- Explain differences with a "why" (e.g. comparative overviews) | +% | [Sibling pages](/versions/content-patterns.md#sibling-pages) | When the information is too complex to be addressed with only the other content patterns. See specific examples in the sibling pages section. | + +% | [List item suffixes](/versions/content-patterns.md#list-item-suffixes) | Identify features in a **list of features** that are exclusive to a specific context, or that were introduced in a specific version. | +% | [Sibling bullets](/versions/content-patterns.md#sibling-bullets) | List differing requirements, limits, and other simple, mirrored facts. | \ No newline at end of file diff --git a/docs/contribute/cumulative-docs/best-practices.md b/docs/contribute/cumulative-docs/best-practices.md new file mode 100644 index 000000000..1aa1717e4 --- /dev/null +++ b/docs/contribute/cumulative-docs/best-practices.md @@ -0,0 +1,310 @@ +--- +navigation_title: Best practices +--- + +# Best practices for using `applies_to` + +Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. + +## General guidelines + +% Reference: Slack conversation +* The `applies_to` badges should not require contributors to add specific Markdown real estate + to the page layout (such as a specific `Version` column in a table). + Instead, contributors should be able to add them anywhere they need, and the system should + be in charge of rendering them clearly. + +% Reference: https://github.com/elastic/kibana/pull/229485/files#r2231876006 +* Avoid using version numbers in prose adjacent to `applies_to` badge to prevent + confusion when the badge is rended with `Planned` ahead of a release. + +% Reference: https://github.com/elastic/kibana/pull/229485/files#r2231850710 +* Create hierarchy of versioned information?? + +% Reference: https://elastic.github.io/docs-builder/versions/#defaults-and-hierarchy +* Do not assume a default deployment type, stack flavor, product version, or project type. + Treat all flavors and deployment types equally. Don't treat one as the "base" and the other as the "exception". + +## Order of items + +**Versions.** Always put the newest version first when listing multiple versions. As a result, the lifecycles should be in order of product development progression, too. + +% Reference: https://elastic.github.io/docs-builder/versions/#defaults-and-hierarchy +% Needs work... +**Keys.** Always list [keys](/contribute/cumulative-docs/reference.md#key) in the same order for consistency. The order of keys should reflect organizational priorities. For example, use the following order: +* **Serverless/Elastic Stack**: Serverless, Stack +* **Deployment types**: Elastic Cloud Serverless, Elastic Cloud Hosted, Elastic Cloud on Kubernetes, Elastic Cloud Enterprise, Self-managed +* **Monitoring for Java applications**: Elastic Distribution of OpenTelemetry (EDOT) Java, APM Java agent + +## Placement of badges + +### Headings + +Use [section annotations](/syntax/applies.md#section-annotations) immediately after a heading when the entire content between that heading and the next [heading](/syntax/headings.md) of the same or higher level is version or product-specific. + +For example, in the [Semantic text field type](https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/semantic-text#custom-by-pipelines) page, all the content in this section is only applicable to Elastic Stack versions 9.0.0 and later. + +::::{image} ./images/heading-correct.png +:screenshot: +:alt: Correct use of applies_to with headings +:::: + +:::{warning} +Do **not** use [inline annotations](/syntax/applies.md#inline-annotations) with headings, which will cause rendering issues in _On this page_. + +::::{image} ./images/heading-incorrect.png +:screenshot: +:alt: Rendering error when using inline applies_to with headings +:::: +::: + + +### Definition lists + +The recommended placement of `applies_to` badges in definition lists varies based what part(s) of the list item relate to the badge. + +#### If the badge is relevant to the entire contents of a list item, put it at the end of the term [definition-list-item-full] + +This means using an inline annotation at the end of the same line as the term. For example, on the Kibana [Advanced settings](https://www.elastic.co/docs/reference/kibana/advanced-settings#kibana-banners-settings) page, the entire `banners:linkColor` option is only available in Elastic Stack 9.1.0 and later. + +:::{image} ./images/definition-list-entire-item.png +:screenshot: +:alt: Correct use of applies_to with definition list item +::: + +:::{warning} +Do **not** put the `applies_to` badge at the beginning or end of the definition if it relates to the entire contents of the item. + +::::{image} ./images/definition-list-item-incorrect.png +:screenshot: +:alt: Incorrectly using inline applies_to with a definition list item +:::: +::: + +#### If the badge is only relevant to a portion of the definition, follow the appropriate placement guidelines for the elements used in the definition [definition-list-item-part] + +This might include labeling just one of multiple paragraphs or one item in an ordered or unordered list. For example, on the ... page, ... + +::::{image} ./images/definition-list-portion-correct.png +:screenshot: +:alt: Correctly using inline applies_to in a portion of a definition list item +:::: + + +### Ordered and unordered lists + +Reorganize content as needed so the `applies_to` badge is relevant to the entire contents of the list item. +The recommended placement of the badge varies based on the purpose of the list. + +#### If the purpose of the list is to illustrate the difference between situations, put a badge at the start of each item [list-compare-applies_to] + +This could mean distinguishing between deployment types, products, lifecycles, or versions. +Placing the badge at the beginning of the list item, allows the reader to scan the list for the item that is relevant to them. + +For example, the [Alerting and action settings in Kibana](https://www.elastic.co/docs/reference/kibana/configuration-reference/alerting-settings) page lists how the default value for the `xpack.actions.preconfigured..config.defaultModel` setting varies in Serverless/Stack and across versions. + +::::{image} ./images/list-correct.png +:screenshot: +:alt: +:::: + +#### If the list just happens to have one or more items that are only relevant to a specific situation, put the badge at the end of the list item [list-other] + +Placing the badge at the end of the list item maintains the flow of the list without distracting the reader with badges while still making it clear that the content in that list item is only applicable to the specified situation. + +For example, the [Add filter controls](https://www.elastic.co/docs/explore-analyze/dashboards/add-controls) page lists ways to configure ES|QL controls. Only one of the ways they can be controlled was added for the first time in 9.1.0. + +::::{image} ./images/list-misc-correct.png +:screenshot: +:alt: +:::: + + +% Reference: Slack conversation +### Tables + +The recommended placement in tables varies based on what part(s) of the table related to the `applies_to` label. + +#### If the badge is relevant to the entire row, add the badge to the end of the first column [table-row] + +For example, a table that contains one setting per row and a new setting is added in 9.1.0. + + + +#### If the badge is relevant to one cell or part of a cell, add the badge to the cell it applies to [table-cell] + +For example, a new property is available in 9.1.0 for a setting that already existed before 9.1.0. + + + +#### If the badge is relevant to part of a cell, add the badge to the end of the line it applies to [table-cell-part] + +For example, a new property is available in 9.1.0 for a setting that already existed before 9.1.0. + + + +% Reference: https://github.com/elastic/kibana/pull/229485/files#r2231856744 +:::{tip} +If needed, break the contents of the cell into multiple lines using `
` to isolate the content you're labeling. + + +::: + +### Tabs + +In the future ([elastic/docs-builder#1436](https://github.com/elastic/docs-builder/issues/1436)), tabs will be able to accept `applies_to` information. Until then, if an `applies_to` badge is relevant to the entire tab item, add the badge to the beginning of the content. + + + +### Admonitions + +In the future ([elastic/docs-builder#1436](https://github.com/elastic/docs-builder/issues/1436)), admonitions will be able to accept `applies_to` information. Until then, if an `applies_to` badge is relevant to the entire admonition, add the badge to the beginning of the content. + +::::{image} ./images/admonition-correct.png +:screenshot: +:alt: +:::: + +### Dropdowns + +In the future ([elastic/docs-builder#1436](https://github.com/elastic/docs-builder/issues/1436)), dropdowns will be able to accept `applies_to` information. Until then, if an `applies_to` badge is relevant to the entire dropdown, add the badge to the beginning of the content. + + + +### Code blocks + +To specify `applies_to` information for a code block, refer to [](/contribute/cumulative-docs/content-patterns.md#code-block). + +### Images + +To specify `applies_to` information for an image, refer to [](/contribute/cumulative-docs/content-patterns.md#screenshot). + + + + diff --git a/docs/contribute/cumulative-docs/content-patterns.md b/docs/contribute/cumulative-docs/content-patterns.md new file mode 100644 index 000000000..728076e28 --- /dev/null +++ b/docs/contribute/cumulative-docs/content-patterns.md @@ -0,0 +1,383 @@ +--- +navigation_title: "Example scenarios" +--- + +# Example scenarios + +## Code block content varies [code-block] + +Often the content in a code block will vary between situations (versions, deployment types, etc). +There are a couple possible solutions. + +### Solution A: Use a code callout [code-block-callout] + +Using a code callout is the lightest-touch solution, but might not be sufficient in all cases. + +**When to use a code callout**: + +* The code block and its callouts fit vertically on a typical laptop screen. + This will reduce the risk of users copying the code snippet without reading the information in the callout. +* Syntax is either just added or just removed — syntax is not modified. + It is difficult to communicate that some syntax is needed in more than one situation but varies depending on the situation. +* The code block will not require more than 3 `applies_to`-related callouts. + At that point, the code becomes more difficult to read and use. + +**Best practices**: + +* Place the badge at the beginning of the callout. + +**Example**: A new option was made available in 9.1.0. + +::::{image} ./images/example-code-block-callout.png +:screenshot: +:alt: +:::: + +### Solution B: Use tabs [code-block-tabs] + +**When to use tabs**: If using a [code callout](#code-block-callout) isn't appropriate. + +**Best practices**: + +* Try to minimize the number of tabs where possible, + but do not mix tabs and `applies_to`-related code callouts. +* Try not to include information surrounding a code block in the tabs. + Make the tab content as small as possible apart from the procedure itself. + +**Example**: + +::::{image} ./images/example-code-block-tabs.png +:screenshot: +:alt: +:::: + +## Workflows vary [workflow] + +When one or more steps in a process differs. + +### Solution A: Use inline `applies_to` [workflow-inline] + +Using inline `applies_to` badges to a few line items in an ordered list is the lightest-touch solution, +but might not be sufficient in all cases. + +**When to use inline `applies_to`**: + +* Workflow steps that vary between situations can be easily isolated. +* Each step that varies, only varies between 3 or fewer situations (deployment types, versions, etc). +* There are no more than 3 steps that need to be split into multiple lines with `applies_to` badges. + +**Best practices**: + +* Follow the [best practices for ordered and unordered lists](/contribute/cumulative-docs/best-practices.md#ordered-and-unordered-lists) + including the order of items and the placement of labels. + +**Example**: Only one item in an ordered list varies between Serverless and stateful. + +::::{image} ./images/workflow-inline.png +:screenshot: +:alt: +:::: + +### Solution B: Use tabs [workflow-tabs] + +Tabs are minimally disruptive in many situations. + +**When to use tabs**: + +* Using [inline `applies_to` badges](#workflow-inline) isn't appropriate. +* All the tabs fit horizontally on a single row on a typical laptop screen. + This is usually around a maximum of four tabs. +* The tab with the most content fits vertically on a typical laptop screen. + This is usually around of 20 lines. + +**Best practices**: + +* Try to minimize the number of tabs where possible. Try to work around small differences by + rewording or adding context in prose or in `note` style admonitions. +* Try not to include information surrounding a procedure in the tabs. + Make the tab content as small as possible apart from the procedure itself. +* Consider breaking up procedures into sets of procedures if only one section differs between contexts. + +**Example**: + + + +### Solution C: Use sibling pages [workflow-sibling-pages] + +Sibling pages are a last resort when no other solutions are appropriate. + +**When to use sibling pages**: + +* Neither [inline `applies_to` badges](#workflow-inline) or [tabs](#workflow-tabs) are appropriate. +* The workflow has significant differences across multiple procedures. +* There are chained procedures where not all of the procedures are needed for all contexts + or where the flow across procedures is muddied when versioning context is added. +* The workflow exists in a very complex page that is already heavily using tabs and other tools we use for versioning differences. + This makes it difficult to add another “layer” of content. +% * Beta to GA transitions? Hide the beta doc and leave it linked to the GA doc, which will presumably be more stable? + +**Best practices**: + +**Example**: + +## Screenshots vary [screenshot] + +### Solution A: Use tabs [screenshot-tabs] + +**When to use tabs**: + +**Best practices**: + +**Example**: + +### Solution B: Add a note [screenshot-note] + +**When to use a note**: + +**Best practices**: + +**Example**: + +## Multiple adjacent block elements vary [multiple-block] + +### Solution A: Use headings [multiple-block-headings] + +**When to use headings**: + +**Best practices**: + +**Example**: + +### Solution B: Use tabs [multiple-block-tabs] + +**When to use tabs**: + +**Best practices**: + +**Example**: + +## Feature in beta or technical preview is removed [beta-removed] + +### Solution [beta-removed-solution] + +% ## Tabs +% +% **Use case:** When one or more steps in a process differs, put the steps into tabs - one for each process. +% +% **Number to use:** Max 4 or 5 (in a deployment type / versioning context - might be different for other situations) +% +% Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose or in `note` style admonitions. Check out the [prose](#prose) guidelines. +% +% Try not to include information surrounding a procedure in the tabs. Make the tab content as small as possible apart from the procedure itself. +% +% Consider breaking up procedures into sets of procedures if only one section differs between contexts. +% +% :::{tip} +% For consistency, use [substitutions](/syntax/substitutions.md) for the tab labels. +% ::: +% +% ### Examples +% +% To create a space: +% + + + +You can edit all of the space settings you just defined at any time, except for the URL identifier. + +% ## Sibling bullets +% +% **Use case:** Requirements, limits, other simple, mirrored facts. +% +% **Number to use:** Ideal is one per option (e.g. one per deployment type). You might consider nested bullets in limited cases. +% +% ### Examples +% +% ::::{tab-set} +% :group: one-two +% +% :::{tab-item} One +% :sync: one +% +% #### Required permissions +% +% * **{{serverless-short}}**: `Admin` or equivalent +% * **{{stack}} v9**: `kibana_admin` or equivalent +% +% ::: +% :::{tab-item} Two +% :sync: two +% +% #### Create a space +% +% The maximum number of spaces that you can have differs by [what do we call this]: +% +% * **{{serverless-short}}**: Maximum of 100 spaces. +% * **{{stack}} v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. +% ::: +% :::: +% +% ## Callouts +% +% **Use case:** Happy differences, clarifications +% +% Some sections don’t apply to contexts like serverless, because we manage the headache for you. Help people to feel like they’re not getting shortchanged with a callout. +% +% If there’s a terminology change or other minor change (especially where x equates with y), consider handling as a note for simplicity. +% +% ### Examples +% +% * *In **Manage TLS certificates** section*: +% +% :::{tip} +% Elastic Cloud manages TLS certificates for you. +% ::: +% +% * *In a **Spaces** overview*: +% +% :::{note} +% In {{stack}} 9.0.0 and earlier, **Spaces** are referred to as **Places**. +% +% +% ## Prose +% +% **Use cases:** +% * When features in a list of features are exclusive to a specific context, or were introduced in a specific version +% * Requirements, limits, other simple, mirrored facts +% * Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews +% * Comparative overviews +% * Differences that are small enough or not significant enough to warrant an admonition or tabs or separate sections with front matter +% +% In some cases, you might want to add a paragraph specific to one version or another in prose to clarify behavior or terminology. +% +% In cases where there are significant differences between contexts, close explanation of the differences helps people to understand how something works, or why something behaves the way it does. Compare and contrast differences in paragraphs when the explanation helps people to use our features effectively. +% +% You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough. +% +% ### Examples +% +% ::::{tab-set} +% :group: five-six-four-one-three +% +% :::{tab-item} Unique features +% :sync: five +% +% * Each space has its own saved objects. +% * Users can only access the spaces that they have been granted access to. This access is based on user roles, and a given role can have different permissions per space. +% * In {{stack}} 9.0.0+, each space has its own navigation. +% +% ::: +% +% :::{tab-item} Unique reqs / limits +% :sync: six +% +% * In serverless, use `Admin` or equivalent +% * In {{stack}} 9.0.0+, use `kibana_admin` or equivalent +% +% OR +% +% The maximum number of spaces that you can have differs by [what do we call this]: +% +% * In serverless, you can have a maximum of 100 spaces. +% * In {{stack}} 9.0.0+, the maximum is controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. +% ::: +% +% :::{tab-item} Nice-to-know +% :sync: four +% +% In {{stack}} 9.1.0 and earlier, **Spaces** were referred to as **Places**. +% +% OR +% +% If you're managing a {{stack}} v9 deployment, then you can also assign roles and define permissions for a space from the **Permissions** tab of the space settings. +% ::: +% +% :::{tab-item} Comparative overviews +% :sync: one +% +% The way that TLS certificates are managed depends on your deployment type: +% +% In self-managed Elasticsearch, you manage both of these certificates yourself. +% +% In {{eck}}, you can manage certificates for the HTTP layer. Certificates for the transport layer are managed by ECK and can’t be changed. However, you can set your own certificate authority, customize certificate contents, and provide your own certificate generation tools using transport settings. +% +% In {{ece}}, you can use one or more proxy certificates to secure the HTTP layer. These certificates are managed at the ECE installation level. Transport-level encryption is managed by ECE and certificates can’t be changed. +% ::: +% +% :::{tab-item} Comparative overviews II +% :sync: three +% +% **Managed security in Elastic Cloud** +% +% Elastic Cloud has built-in security. For example, HTTPS communications between Elastic Cloud and the internet, as well as inter-node communications, are secured automatically, and cluster data is encrypted at rest. +% +% You can augment Elastic Cloud security features in the following ways: +% +% * Configure traffic filtering to prevent unauthorized access to your deployments. +% * Encrypt your deployment with a customer-managed encryption key. +% * Secure your settings with the Elasticsearch keystore. +% * Allow or deny Cloud IP ranges using Elastic Cloud static IPs. +% +% [Learn more about security measures in Elastic Cloud](https://www.elastic.co/cloud/security). +% +% ::: +% :::: + + +## Sibling pages + +**Number to use:** As few as possible. Consider leveraging other ways of communicating versioning differences to reduce the number of sibling pages. + +**When to use:** + +When version differences are just too large to be handled with any of our other tools. Try to avoid creating sibling pages when you can. + +% Down the line, if we need to, we could easily convert version-sensitive sibling pages into “picker” pages + +### Examples + +[Cloud Hosted deployment billing dimensions](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization/billing/cloud-hosted-deployment-billing-dimensions) + +and its sibling + +[{{serverless-short}} project billing dimensions](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization/billing/serverless-project-billing-dimensions) + + +:::::{tab-set} +:group: serverless-stack + +::::{tab-item} {{serverless-short}} +:sync: serverless + +1. Click **Create space** or select the space you want to edit. +2. Provide: + + * A meaningful name and description for the space. + * A URL identifier. The URL identifier is a short text string that becomes part of the Kibana URL. Kibana suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier later. + +3. Customize the avatar of the space to your liking. +4. Save the space. +:::: + +::::{tab-item} {{stack}} v9 +:sync: stack + +1. Select **Create space** and provide a name, description, and URL identifier. + The URL identifier is a short text string that becomes part of the Kibana URL when you are inside that space. Kibana suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier once you create the space. + +2. Select a **Solution view**. This setting controls the navigation that all users of the space will get: + * **Search**: A light navigation menu focused on analytics and Search use cases. Features specific to Observability and Security are hidden. + * **Observability**: A light navigation menu focused on analytics and Observability use cases. Features specific to Search and Security are hidden. + * **Security**: A light navigation menu focused on analytics and Security use cases. Features specific to Observability and Search are hidden. + * **Classic**: All features from all solutions are visible by default using the classic, multilayered navigation menus. You can customize which features are visible individually. + +3. If you selected the **Classic** solution view, you can customize the **Feature visibility** as you need it to be for that space. + + :::{note} + Even when disabled in this menu, some Management features can remain visible to some users depending on their privileges. Additionally, controlling feature visibility is not a security feature. To secure access to specific features on a per-user basis, you must configure Kibana Security. + ::: +4. Customize the avatar of the space to your liking. +5. Save your new space by selecting **Create space**. +:::: + +::::: \ No newline at end of file diff --git a/docs/contribute/cumulative-docs/example-code-block-tabs.png b/docs/contribute/cumulative-docs/example-code-block-tabs.png new file mode 100644 index 000000000..5938aee02 Binary files /dev/null and b/docs/contribute/cumulative-docs/example-code-block-tabs.png differ diff --git a/docs/contribute/cumulative-docs/images/admonition-correct.png b/docs/contribute/cumulative-docs/images/admonition-correct.png new file mode 100644 index 000000000..120149501 Binary files /dev/null and b/docs/contribute/cumulative-docs/images/admonition-correct.png differ diff --git a/docs/contribute/cumulative-docs/images/definition-list-entire-item.png b/docs/contribute/cumulative-docs/images/definition-list-entire-item.png new file mode 100644 index 000000000..c834684d4 Binary files /dev/null and b/docs/contribute/cumulative-docs/images/definition-list-entire-item.png differ diff --git a/docs/contribute/cumulative-docs/images/definition-list-item-incorrect.png b/docs/contribute/cumulative-docs/images/definition-list-item-incorrect.png new file mode 100644 index 000000000..05914dc9f Binary files /dev/null and b/docs/contribute/cumulative-docs/images/definition-list-item-incorrect.png differ diff --git a/docs/contribute/cumulative-docs/images/definition-list-portion-correct.png b/docs/contribute/cumulative-docs/images/definition-list-portion-correct.png new file mode 100644 index 000000000..8110538e6 Binary files /dev/null and b/docs/contribute/cumulative-docs/images/definition-list-portion-correct.png differ diff --git a/docs/contribute/cumulative-docs/images/example-code-block-callout.png b/docs/contribute/cumulative-docs/images/example-code-block-callout.png new file mode 100644 index 000000000..45baa8fb8 Binary files /dev/null and b/docs/contribute/cumulative-docs/images/example-code-block-callout.png differ diff --git a/docs/contribute/cumulative-docs/images/example-code-block-tabs.png b/docs/contribute/cumulative-docs/images/example-code-block-tabs.png new file mode 100644 index 000000000..935bd23e8 Binary files /dev/null and b/docs/contribute/cumulative-docs/images/example-code-block-tabs.png differ diff --git a/docs/contribute/cumulative-docs/images/heading-correct.png b/docs/contribute/cumulative-docs/images/heading-correct.png new file mode 100644 index 000000000..1f7b515af Binary files /dev/null and b/docs/contribute/cumulative-docs/images/heading-correct.png differ diff --git a/docs/contribute/cumulative-docs/images/heading-incorrect.png b/docs/contribute/cumulative-docs/images/heading-incorrect.png new file mode 100644 index 000000000..96ef77cb5 Binary files /dev/null and b/docs/contribute/cumulative-docs/images/heading-incorrect.png differ diff --git a/docs/contribute/cumulative-docs/images/list-correct.png b/docs/contribute/cumulative-docs/images/list-correct.png new file mode 100644 index 000000000..2483fd0c0 Binary files /dev/null and b/docs/contribute/cumulative-docs/images/list-correct.png differ diff --git a/docs/contribute/cumulative-docs/images/list-misc-correct.png b/docs/contribute/cumulative-docs/images/list-misc-correct.png new file mode 100644 index 000000000..e6da7a477 Binary files /dev/null and b/docs/contribute/cumulative-docs/images/list-misc-correct.png differ diff --git a/docs/contribute/cumulative-docs/images/workflow-inline.png b/docs/contribute/cumulative-docs/images/workflow-inline.png new file mode 100644 index 000000000..53f23f676 Binary files /dev/null and b/docs/contribute/cumulative-docs/images/workflow-inline.png differ diff --git a/docs/contribute/cumulative-docs.md b/docs/contribute/cumulative-docs/index.md similarity index 82% rename from docs/contribute/cumulative-docs.md rename to docs/contribute/cumulative-docs/index.md index 588aba8fb..4d26dc424 100644 --- a/docs/contribute/cumulative-docs.md +++ b/docs/contribute/cumulative-docs/index.md @@ -1,22 +1,30 @@ -# Write cumulative documentation +# Write cumulative documentation -In elastic.co/docs (Docs V3), we write docs cumulatively regardless of the [branching strategy](branching-strategy.md) selected. +In elastic.co/docs (Docs V3), we write docs cumulatively regardless of the [branching strategy](/contribute/branching-strategy.md) selected. -**What does this mean?** +**What does this mean?** With 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. This new behavior starts with the following **versions** of our products: Elastic Stack 9.0, ECE 4.0, ECK 3.0, and even more like EDOT docs. It also includes our unversioned products: Serverless and Elastic Cloud. -:::{note} +:::{note} Nothing changes for our ASCIIDoc-based documentation system, that remains published and maintained for the following versions: Elastic Stack until 8.x, ECE until 3.x, ECK until 2.x, etc. ::: -**How does it change the way we write docs?** +**Why?** + +This approach improves our documentation in several ways: + +* When a user arrives in our documentation from an outside source, they'll be likelier to land on a page or section that applies to them. +* 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. +* Comparing and contrasting differences helps users to understand what is available to them, and improves awareness of the ways certain offerings might improve their experience. + +**How does it change the way we write docs?** 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. @@ -24,14 +32,14 @@ This extends to deprecations and removals: No information should be removed for 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](#tagging-products-and-deployment-models) (for example, Elastic Cloud Serverless or Elastic Cloud Hosted). +* [Which Elastic products and deployment models the content applies to](#tagging-products-and-deployment-models) (for example, Elastic Cloud Serverless or Elastic Cloud Hosted). * [When a feature goes into a new state as compared to the established base version](#tagging-version-related-changes-mandatory) (for example, being added or going from Beta to GA). This tagging system is mandatory for all of the public-facing documentation. We refer to it as “[applies_to](/syntax/applies.md)” tags or badges. ## How version awareness works in Docs V3 -Docs V3 uses a central version config called [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/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). +Docs V3 uses a central version config called [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/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](#how-do-these-tags-behave-in-the-output). This logic allows us to label documentation related to unreleased versions as `planned`, continuously release documentation, and document our Serverless and {{stack}} offerings in one place. @@ -39,9 +47,9 @@ This central version config is used in certain inline version variables, and dri ### Page-level frontmatter (mandatory) -All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use YAML frontmatter to indicate each deployment target's availability and lifecycle status. +All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use YAML frontmatter to indicate each deployment target's availability and lifecycle status. -The `applies_to` attribute is used to display contextual badges on each page. For the full list of supported keys and values, refer to [frontmatter](/syntax/frontmatter.md). +The `applies_to` attribute is used to display contextual badges on each page. For the full list of supported keys and values, refer to [frontmatter](/syntax/frontmatter.md). :::{tip} @@ -65,15 +73,15 @@ When a portion of a page is applicable to a different context than what was spec ### When should I indicate that something is NOT applicable to a specific context? -By default, we communicate that content does not apply to a certain context by simply **not specifying it**. +By default, we communicate that content does not apply to a certain context by simply **not specifying it**. For example, a page describing how to create an {{ech}} deployment just requires identifying "{{ech}}" as context. No need to overload the context with additional `serverless: unavailable` indicators. This is true for most situations. However, it can still be useful to call it out in a few specific scenarios: -* When there is a high risk of confusion for users. This may be subjective, but let’s imagine a scenario where a feature is available in 2 out of 3 serverless project types. It may make sense to clarify and be explicit about the feature being “unavailable” for the 3rd type. For example: +* When there is a high risk of confusion for users. This may be subjective, but let’s imagine a scenario where a feature is available in 2 out of 3 serverless project types. It may make sense to clarify and be explicit about the feature being “unavailable” for the 3rd type. For example: ```yml - --- + --- applies_to: stack: ga serverless: @@ -84,10 +92,10 @@ This is true for most situations. However, it can still be useful to call it out ``` -* When a specific section, paragraph or list item has specific applicability that differs from the context set at the page or section level, and the action is not possible at all for that context (meaning that there is no alternative). For example: +* When a specific section, paragraph or list item has specific applicability that differs from the context set at the page or section level, and the action is not possible at all for that context (meaning that there is no alternative). For example: ````md - --- + --- applies_to: stack: ga serverless: ga @@ -106,16 +114,16 @@ This is true for most situations. However, it can still be useful to call it out ## Tagging version-related changes (mandatory) -In the previous section, we’ve considered product and deployment availability. Feature lifecycle and version-related changes are communicated as part of the same [applies_to](/syntax/applies.md) tagging logic, by specifying different values to each supported key. +In the previous section, we’ve considered product and deployment availability. Feature lifecycle and version-related changes are communicated as part of the same [applies_to](/syntax/applies.md) tagging logic, by specifying different values to each supported key. -**Are you sure your change is related to a specific version? Maybe not…** -This is a frequent case. For example: fixing typos, improving styling, adding a long-forgotten setting, etc. +**Are you sure your change is related to a specific version? Maybe not…** +This is a frequent case. For example: fixing typos, improving styling, adding a long-forgotten setting, etc. For this case, no specific version tagging is necessary. -**A new feature is added to {{serverless-short}} or {{ecloud}}. How do I tag it?** +**A new feature is added to {{serverless-short}} or {{ecloud}}. How do I tag it?** Cumulative documentation is not meant to replace release notes. If a feature becomes available in {{serverless-short}} and doesn’t have a particular lifecycle state to call out (preview, beta, deprecated…), it does not need specific tagging. -However, in this scenario, it is important to consider carefully [when the change is going to be published](branching-strategy.md). +However, in this scenario, it is important to consider carefully [when the change is going to be published](/contribute/branching-strategy.md). We do not do date-based tagging for unversioned products. @@ -127,19 +135,19 @@ We do not do date-based tagging for unversioned products. ### For versioned products :::{include} /syntax/_snippets/versioned-lifecycle.md -::: +::: ### Document features shared between serverless and {{stack}} :::{include} /syntax/_snippets/stack-serverless-lifecycle-example.md ::: -### Identify multiple states for the same content +### Identify multiple states for the same content :::{include} /syntax/_snippets/multiple-lifecycle-states.md ::: - -## How do these tags behave in the output? + +## How do these tags behave in the output? :::{include} /contribute/_snippets/tag-processing.md ::: diff --git a/docs/contribute/cumulative-docs/reference.md b/docs/contribute/cumulative-docs/reference.md new file mode 100644 index 000000000..8ebf83fc2 --- /dev/null +++ b/docs/contribute/cumulative-docs/reference.md @@ -0,0 +1,24 @@ +# Quick reference + +The `applies_to` directive uses the following format: + +``` +: +``` + +This page provides minimal reference information on the `applies_to` directive. For more detailed information, refer to [](/syntax/applies.md). + +## key + +:::{include} /_snippets/applies_to-key.md +::: + +## lifecycle + +:::{include} /_snippets/applies_to-lifecycle.md +::: + +## version + +:::{include} /_snippets/applies_to-version.md +::: diff --git a/docs/contribute/cumulative-docs/workflow-inline.png b/docs/contribute/cumulative-docs/workflow-inline.png new file mode 100644 index 000000000..53f23f676 Binary files /dev/null and b/docs/contribute/cumulative-docs/workflow-inline.png differ diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 209aaf642..a07e14a7e 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -27,7 +27,7 @@ In April 2025, we released our new documentation site. This site includes docume In Docs V3, a single branch is published per repository. This branch is set to `main` by default, but it is possible to instead publish a different branch by changing your repository's deployment model. You might want to change your deployment model so you can have more control over when content added for a specific release is published. -[Learn more about branching strategies](branching-strategy.md). +[Learn more about branching strategies](/contribute/branching-strategy.md). ### Contribute to elastic.co/guide diff --git a/docs/contribute/locally.md b/docs/contribute/locally.md index 15d1ce815..9f0d0eec5 100644 --- a/docs/contribute/locally.md +++ b/docs/contribute/locally.md @@ -23,14 +23,14 @@ This guide follows the first option. If you'd like to clone the repository and b ::::{tab-item} macOS & Linux -1. **Download and run the install script** +1. **Download and run the install script** Run this command to download and install the latest version of `docs-builder`: ```sh curl -sL https://ela.st/docs-builder-install | sh ``` - + This downloads the latest binary to `/usr/local/bin`, makes it an executable, and installs it to your user PATH. This means you can use the `docs-builder` command from any location of your machine to deploy and run documentation repositories like `docs-builder`, `docs-content` and so on. You can optionally specify a specific version to install: @@ -53,7 +53,7 @@ This guide follows the first option. If you'd like to clone the repository and b Run `docs-builder` without `serve` to run a full build and detect errors. ::: -To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub. +To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub. If you get a `Permission denied` error, make sure that you aren't trying to run a directory instead of a file. Also, grant the binary file execution permissions using `chmod +x docs-builder`. @@ -61,7 +61,7 @@ If you get a `Permission denied` error, make sure that you aren't trying to run ::::{tab-item} Windows -1. **Download and run the install script** +1. **Download and run the install script** Run this command to download and install the latest version of `docs-builder`: @@ -106,7 +106,7 @@ git clone https://github.com/elastic/docs-content.git We write docs in Markdown. Refer to our [syntax](../syntax/index.md) guide for the flavor of Markdown we support and all of our custom directives that enable you to add a little extra pizzazz to your 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](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). :::{include} _snippets/tagged-warning.md ::: diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md index 352869833..d28ff9d71 100644 --- a/docs/migration/versioning.md +++ b/docs/migration/versioning.md @@ -7,8 +7,8 @@ To ensure a seamless experience for users and contributors, the new versioning a * **Context awareness**: Each page explicitly states the context it applies to, including relevant deployment types (e.g., Elastic Cloud Hosted and Elastic Cloud Serverless) and versions. This is communicated using [`applies_to` tags](/syntax/applies.md). Context clarity ensures users know if the content is applicable to their environment. When users land on a Docs page that doesn’t apply to their version or deployment type, clear cues and instructions will guide them to the appropriate content. * **Version awareness**: The documentation team tracks and maintains released versions for all products in a central configuration file. * **Simplified contributor workflow**: For pages that apply to multiple versions or deployment types, we’ve optimized the contributor experience by reducing complexity. Contributors can now manage multi-context content with ease, without duplicating information or navigating confusing workflows. - -In this new system, documentation is written **cumulatively**. 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). + +In this new system, documentation is written **cumulatively**. 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). ## Tag processing @@ -17,7 +17,7 @@ In this new system, documentation is written **cumulatively**. This means that a ## Branching strategy -In Docs V3, a single branch is published per repository. This branch is set to `main` by default, but it is possible to instead publish a different branch by changing your repository's branching strategy. 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 Docs V3, a single branch is published per repository. This branch is set to `main` by default, but it is possible to instead publish a different branch by changing your repository's branching strategy. You might want to change your branching strategy so you can have more control over when content added for a specific release is published. * [Learn how to choose the right branching strategy for your repository](/contribute/branching-strategy.md) * [Learn how to set up your selected branching strategy](/configure/content-sources.md) diff --git a/docs/syntax/_snippets/stack-serverless-lifecycle-example.md b/docs/syntax/_snippets/stack-serverless-lifecycle-example.md index 5e2c9ae08..2ef928649 100644 --- a/docs/syntax/_snippets/stack-serverless-lifecycle-example.md +++ b/docs/syntax/_snippets/stack-serverless-lifecycle-example.md @@ -8,14 +8,14 @@ applies_to: --- ``` -Because these changes need to be published as soon as the feature is released in Serverless, you might need to publish your docs before the feature is available in the {{stack}}. To allow for this, Docs V3 [displays badges differently](/contribute/cumulative-docs.md#how-do-these-tags-behave-in-the-output) when the `applies_to` tag specifies a product version that has not yet been released to customers. +Because these changes need to be published as soon as the feature is released in Serverless, you might need to publish your docs before the feature is available in the {{stack}}. To allow for this, Docs V3 [displays badges differently](/contribute/cumulative-docs/index.md#how-do-these-tags-behave-in-the-output) when the `applies_to` tag specifies a product version that has not yet been released to customers. -* A feature is tagged as available in a current Serverless release and a future {{stack}} version will render the following badges: +* A feature is tagged as available in a current Serverless release and a future {{stack}} version will render the following badges: {applies_to}`serverless: ga` {applies_to}`stack: ga 99.99` -* After the {{stack}} version is released, the same badges will render with the version number without any changes to the badge value in the source. +* After the {{stack}} version is released, the same badges will render with the version number without any changes to the badge value in the source. {applies_to}`serverless: ga` {applies_to}`stack: ga 9.0` \ No newline at end of file diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 8de237b32..fe96d79a1 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,11 +1,10 @@ # Applies to - -Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a [cumulative approach](../contribute/cumulative-docs.md): instead of creating separate pages for each product and release, we update a single page with product- and version-specific details over time. +Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a [cumulative approach](/contribute/cumulative-docs/index.md): instead of creating separate pages for each product and release, we update a single page with product- and version-specific details over time. To support this, source files use a tagging system to indicate: @@ -51,7 +50,7 @@ been established earlier. ❌ If the product is not versioned (meaning all users are always on the latest version, like in serverless or cloud), you do not need to tag a new GA feature. -For detailed guidance, refer to [](/contribute/cumulative-docs.md). +For detailed guidance, refer to [](/contribute/cumulative-docs/index.md). ## Syntax @@ -72,20 +71,20 @@ Where: Note that a key without any value doesn't show any badge in the output. -### Lifecycle +### Key -`applies_to` accepts the following lifecycle states: +:::{include} /_snippets/applies_to-key.md +::: -* `preview` -* `beta` -* `deprecated` -* `removed` -* `unavailable` -* `ga` +### Lifecycle + +:::{include} /_snippets/applies_to-lifecycle.md +::: ### Version -Can be in either `major.minor` or `major.minor.patch` format +:::{include} /_snippets/applies_to-version.md +::: Versioned products require a `version` tag to be used with the `lifecycle` tag. See [Syntax](#syntax): @@ -254,7 +253,7 @@ applies_to: ```{applies_to} stack: preview 9.1 -serverless: planned +serverless: ga apm_agent_dotnet: ga 1.0.0 apm_agent_java: beta 1.0.0 @@ -274,9 +273,9 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam sit amet auctor odio. Donec ac placerat nunc. {applies_to}`stack: preview` Aenean scelerisque viverra lectus nec dignissim. Vestibulum ut felis nec massa auctor placerat. Maecenas vel dictum. -- {applies_to}`elasticsearch: preview` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. +- {applies_to}`elasticsearch: preview` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. - {applies_to}`observability: preview` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. -- {applies_to}`security: preview` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. Aenean scelerisque viverra lectus nec dignissim. +- {applies_to}`security: preview` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. Aenean scelerisque viverra lectus nec dignissim. #### Stack diff --git a/docs/syntax/quick-ref.md b/docs/syntax/quick-ref.md index fda7b5b65..06548407a 100644 --- a/docs/syntax/quick-ref.md +++ b/docs/syntax/quick-ref.md @@ -83,7 +83,7 @@ These examples show the syntax first, followed by the rendered admonition. ## Anchors -A default anchor is automatically created for each [heading](#headings), in the form `#heading-text` (hyphenated, lowercase, special characters and spaces trimmed). To create a custom anchor, add it in square brackets at the end of a heading: `[my-better-anchor]` +A default anchor is automatically created for each [heading](#headings), in the form `#heading-text` (hyphenated, lowercase, special characters and spaces trimmed). To create a custom anchor, add it in square brackets at the end of a heading: `[my-better-anchor]` :::{dropdown} Default anchor ```markdown @@ -114,7 +114,7 @@ A default anchor is automatically created for each [heading](#headings), in the ## Applies to -Tags that identify technical contexts: the feature base (stack/serverless), deployments, and project types that a piece of content "applies to." Use `applies_to` tags to help users determine whether content is right for their deployments and configuration. These tags are a [version content pattern](../versions/content-patterns.md) in Elastic Docs v3. +Tags that identify technical contexts: the feature base (stack/serverless), deployments, and project types that a piece of content "applies to." Use `applies_to` tags to help users determine whether content is right for their deployments and configuration. These tags are a [version content pattern](/contribute/cumulative-docs/content-patterns.md) in Elastic Docs v3. **Example: Section tag** @@ -122,7 +122,7 @@ Tags that identify technical contexts: the feature base (stack/serverless), depl ````markdown # Stack-only content ```{applies_to} -stack: +stack: ``` ```` ::: @@ -276,9 +276,9 @@ Use `%` to add single-line comments. Use HTML-style `` for multi-l This is regular text Regular text after multi-line comment @@ -290,9 +290,9 @@ Use `%` to add single-line comments. Use HTML-style `` for multi-l This is regular text Regular text after multi-line comment @@ -311,7 +311,7 @@ Regular text after multi-line comment ## Dropdowns -Collapsible blocks for hiding and showing content. +Collapsible blocks for hiding and showing content. ::::{dropdown} Syntax ```markdown @@ -341,7 +341,7 @@ Collapsible content --- ## Headings -Title of a page or a section. To create a heading, add number signs `#` at the beginning of the line (one `#` for each heading level). +Title of a page or a section. To create a heading, add number signs `#` at the beginning of the line (one `#` for each heading level). :::{dropdown} Syntax ```markdown @@ -390,8 +390,8 @@ Standard Markdown images: `[alt text]` in square brackets, followed by the image ::: **DOs**
-✅ **Do:** Store images in a centralized directory
-✅ **Do:** Follow v3 [best practices for screenshots](../versions/index.md#screenshots)
+✅ **Do:** Store images in a centralized directory
+✅ **Do:** Follow v3 [best practices for screenshots](/contribute/cumulative-docs/best-practices.md#screenshots)
✅ **Do:** Specify `:screenshot:` in an [image directive](images.md#screenshots) to add a border **DON'Ts**
@@ -406,14 +406,14 @@ Standard Markdown images: `[alt text]` in square brackets, followed by the image --- -## Inline formatting +## Inline formatting Elastic Docs v3 supports standard Markdown inline formatting. `_emphasis_`     _italics_
`**strong**`    **bold**
\` `monospace` \`     `inline code` (single backticks)
`~~strikethrough~~`     ~~strikethrough~~
-`\* escaped`     \* escaped character +`\* escaped`     \* escaped character **DOs**
✅ **Do:** Use `_emphasis_` to introduce a term
@@ -491,7 +491,7 @@ Standard Markdown ordered (numbered) and unordered (bulleted) lists. Indent with ## Navigation title -Optional [front matter](frontmatter.md) element that sets a custom title for docs navigation features: appears in the left nav (table of contents), breadcrumbs, and previous/next links. Compare [headings](#headings) (H1 = page title). +Optional [front matter](frontmatter.md) element that sets a custom title for docs navigation features: appears in the left nav (table of contents), breadcrumbs, and previous/next links. Compare [headings](#headings) (H1 = page title). :::{dropdown} Syntax @@ -499,14 +499,14 @@ Page front matter (yaml): ```yaml --- - navigation_title: "Minimalist identifier" + navigation_title: "Minimalist identifier" --- ``` -Page title (Markdown H1): +Page title (Markdown H1): ```markdown - # Full descriptive page title with product context + # Full descriptive page title with product context ``` ::: @@ -534,7 +534,7 @@ Page title (Markdown H1): --- -## Substitutions +## Substitutions Key-value pairs that define reusable variables. They help ensure consistency and enable short forms. To use a substitution (or "sub"), surround the key with curly brackets: `{{variable}}`
% TODO: link to our global docset.yml? @@ -576,11 +576,11 @@ Elastic Cloud Hosted supports most standard Kibana settings. **DOs**
✅ **Do:** Check the global `docset.yml` file for existing product and feature name subs
✅ **Do:** Use substitutions in code blocks by setting `subs=true`
-✅ **Do:** Define new page-specific substitutions as needed +✅ **Do:** Define new page-specific substitutions as needed **DON'Ts**
❌ **Don't:** Override a `docset.yml` sub by defining a page-level sub with the same key (causes build errors)
-❌ **Don't:** Use substitutions for common words that don't need to be standardized +❌ **Don't:** Use substitutions for common words that don't need to be standardized [More details: Substitutions →](./substitutions.md)
@@ -643,22 +643,22 @@ Tab 2 content ## Tables -Standard table layout for structured data. Automatically scrolls horizontally if needed. The **header** row is optional. +Standard table layout for structured data. Automatically scrolls horizontally if needed. The **header** row is optional. :::{dropdown} Syntax ```markdown | Header | Header | | ------ | ------ | - | Data | Info | - | Info | Data | + | Data | Info | + | Info | Data | ``` ::: :::{dropdown} Output | Header | Header | | ------ | ------ | -| Data | Info | -| Info | Data | +| Data | Info | +| Info | Data | ::: **DOs**
diff --git a/docs/versions/_snippets/content-patterns-list.md b/docs/versions/_snippets/content-patterns-list.md deleted file mode 100644 index 4157477bb..000000000 --- a/docs/versions/_snippets/content-patterns-list.md +++ /dev/null @@ -1,11 +0,0 @@ -| Approach | Use case | -| --- | --- | -| [Page-level `applies` tags](/versions/content-patterns.md#page-level-applies-tags) | Provide signals that a page applies to the reader. | -| [Section/heading-level `applies` tags](/versions/content-patterns.md#sectionheading-level-applies-tags) | Provide signals about a section’s scope so a user can choose to read or skip it as needed. | -| [Tabs](/versions/content-patterns.md#tabs) | Provide two sets of procedures when one or more steps in a process differs between contexts or versions. | -| [Callouts](/versions/content-patterns.md#callouts) | Draw attention to happy differences and basic clarifications. | -| [Prose](/versions/content-patterns.md#prose) | - Identify features in a list of features that are exclusive to a specific context, or that were introduced in a specific version
- List differing requirements, limits, and other simple, mirrored facts
- Provide clarifying or secondary information
- Explain differences with a "why" (e.g. comparative overviews) | -| [Sibling pages](/versions/content-patterns.md#sibling-pages) | When the information is too complex to be addressed with only the other content patterns. See specific examples in the sibling pages section. | - -% | [List item suffixes](/versions/content-patterns.md#list-item-suffixes) | Identify features in a **list of features** that are exclusive to a specific context, or that were introduced in a specific version. | -% | [Sibling bullets](/versions/content-patterns.md#sibling-bullets) | List differing requirements, limits, and other simple, mirrored facts. | \ No newline at end of file diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md deleted file mode 100644 index 64f30caf6..000000000 --- a/docs/versions/content-patterns.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -navigation_title: "Content patterns" ---- - -# Version content patterns - -:::{warning} -This documentation may be out of date. For updated guidance, refer to [](/contribute/cumulative-docs.md). -::: - -Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. - -Choose from: - -:::{include} _snippets/content-patterns-list.md -::: - -## Page-level `applies` tags - -*see [`applies`](/syntax/applies.md)* - -**Use case:** Provide signals that a page applies to the reader - -**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.md#basic-concepts-and-principles). - -**Approach:** - -Add tags for all **versioning facets** relevant to the page. - -See [Versions and lifecycle states](/versions/index.md#versions-and-lifecycle-states) to learn when to specify versions in these tags. - -### Examples - -[Manage your Cloud organization](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization) - -## Section/heading-level `applies` tags - -```yaml {applies_to} -stack: ga 9.1 -deployment: - eck: ga 9.0 - ece: removed 9.2.0 - self: unavailable 9.3.0 -``` - -*see [`applies`](/syntax/applies.md#section-annotations)* - -**Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed - -**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.md#basic-concepts-and-principles). - -**When to use:** When the section-level scope differs from the page-level scope - -**Example** -See above - -% ## List item suffixes -% -% **Use case:** When features in a **list of features** are exclusive to a specific context, or were introduced in a specific version -% -% **Number to use:** Three max. If the number of tags is longer than that, consider: -% -% * Breaking up the list by facet -% * Using labels that don't have version / lifecycle information and deferring that information to the page or section for the feature -% -% **Approach:** -% -% Append the information to the bullet item in bolded square brackets `**[]**`. Add all information within a single set of square brackets. The brackets should appear after any final punctuation. Consider using words like `only` to help people to understand that this information indicates the applicability of a feature. -% -% ### Examples -% -% Spaces let you organize your content and users according to your needs. -% -% ::::{tab-set} -% :group: one-two -% -% :::{tab-item} One -% :sync: one -% -% * Each space has its own saved objects. -% * Users can only access the spaces that they have been granted access to. This access is based on user roles, and a given role can have different permissions per space. -% * Each space has its own navigation. **[{{stack}} v9 only]** -% -% ::: -% :::{tab-item} Two -% :sync: two -% -% -% * Learn about internal users, which are responsible for the operations that take place inside an Elasticsearch cluster -% * Learn about service accounts, which are used for integration with external services that connect to Elasticsearch -% * Learn about the services used for token-based authentication -% * Learn about the services used by orchestrators **[Elastic Cloud Hosted, {{ece}}, {{eck}}]** -% * Learn about user lookup technologies -% * Manage the user cache -% -% ::: -% :::: - - -## Tabs - -**Use case:** When one or more steps in a process differs, put the steps into tabs - one for each process. - -**Number to use:** Max 4 or 5 (in a deployment type / versioning context - might be different for other situations) - -Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose or in `note` style admonitions. Check out the [prose](#prose) guidelines. - -Try not to include information surrounding a procedure in the tabs. Make the tab content as small as possible apart from the procedure itself. - -Consider breaking up procedures into sets of procedures if only one section differs between contexts. - -:::{tip} -For consistency, use [substitutions](/syntax/substitutions.md) for the tab labels. -::: - -### Examples - -To create a space: - -:::::{tab-set} -:group: serverless-stack - -::::{tab-item} {{serverless-short}} -:sync: serverless - -1. Click **Create space** or select the space you want to edit. -2. Provide: - - * A meaningful name and description for the space. - * A URL identifier. The URL identifier is a short text string that becomes part of the Kibana URL. Kibana suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier later. - -3. Customize the avatar of the space to your liking. -4. Save the space. -:::: - -::::{tab-item} {{stack}} v9 -:sync: stack - -1. Select **Create space** and provide a name, description, and URL identifier. - The URL identifier is a short text string that becomes part of the Kibana URL when you are inside that space. Kibana suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier once you create the space. - -2. Select a **Solution view**. This setting controls the navigation that all users of the space will get: - * **Search**: A light navigation menu focused on analytics and Search use cases. Features specific to Observability and Security are hidden. - * **Observability**: A light navigation menu focused on analytics and Observability use cases. Features specific to Search and Security are hidden. - * **Security**: A light navigation menu focused on analytics and Security use cases. Features specific to Observability and Search are hidden. - * **Classic**: All features from all solutions are visible by default using the classic, multilayered navigation menus. You can customize which features are visible individually. - -3. If you selected the **Classic** solution view, you can customize the **Feature visibility** as you need it to be for that space. - - :::{note} - Even when disabled in this menu, some Management features can remain visible to some users depending on their privileges. Additionally, controlling feature visibility is not a security feature. To secure access to specific features on a per-user basis, you must configure Kibana Security. - ::: -4. Customize the avatar of the space to your liking. -5. Save your new space by selecting **Create space**. -:::: - -::::: - -You can edit all of the space settings you just defined at any time, except for the URL identifier. - -% ## Sibling bullets -% -% **Use case:** Requirements, limits, other simple, mirrored facts. -% -% **Number to use:** Ideal is one per option (e.g. one per deployment type). You might consider nested bullets in limited cases. -% -% ### Examples -% -% ::::{tab-set} -% :group: one-two -% -% :::{tab-item} One -% :sync: one -% -% #### Required permissions -% -% * **{{serverless-short}}**: `Admin` or equivalent -% * **{{stack}} v9**: `kibana_admin` or equivalent -% -% ::: -% :::{tab-item} Two -% :sync: two -% -% #### Create a space -% -% The maximum number of spaces that you can have differs by [what do we call this]: -% -% * **{{serverless-short}}**: Maximum of 100 spaces. -% * **{{stack}} v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. -% ::: -% :::: - -## Callouts - -**Use case:** Happy differences, clarifications - -Some sections don’t apply to contexts like serverless, because we manage the headache for you. Help people to feel like they’re not getting shortchanged with a callout. - -If there’s a terminology change or other minor change (especially where x equates with y), consider handling as a note for simplicity. - -### Examples - -* *In **Manage TLS certificates** section*: - - :::{tip} - Elastic Cloud manages TLS certificates for you. - ::: - -* *In a **Spaces** overview*: - - :::{note} - In {{stack}} 9.0.0 and earlier, **Spaces** are referred to as **Places**. - -## Prose - -**Use cases:** -* When features in a list of features are exclusive to a specific context, or were introduced in a specific version -* Requirements, limits, other simple, mirrored facts -* Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews -* Comparative overviews -* Differences that are small enough or not significant enough to warrant an admonition or tabs or separate sections with front matter - -In some cases, you might want to add a paragraph specific to one version or another in prose to clarify behavior or terminology. - -In cases where there are significant differences between contexts, close explanation of the differences helps people to understand how something works, or why something behaves the way it does. Compare and contrast differences in paragraphs when the explanation helps people to use our features effectively. - -% You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough. - -### Examples - - -::::{tab-set} -:group: five-six-four-one-three - -:::{tab-item} Unique features -:sync: five - -* Each space has its own saved objects. -* Users can only access the spaces that they have been granted access to. This access is based on user roles, and a given role can have different permissions per space. -* In {{stack}} 9.0.0+, each space has its own navigation. - -::: - -:::{tab-item} Unique reqs / limits -:sync: six - -* In serverless, use `Admin` or equivalent -* In {{stack}} 9.0.0+, use `kibana_admin` or equivalent - -OR - -The maximum number of spaces that you can have differs by [what do we call this]: - -* In serverless, you can have a maximum of 100 spaces. -* In {{stack}} 9.0.0+, the maximum is controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. -::: - -:::{tab-item} Nice-to-know -:sync: four - -In {{stack}} 9.1.0 and earlier, **Spaces** were referred to as **Places**. - -OR - -If you're managing a {{stack}} v9 deployment, then you can also assign roles and define permissions for a space from the **Permissions** tab of the space settings. -::: - -:::{tab-item} Comparative overviews -:sync: one - -The way that TLS certificates are managed depends on your deployment type: - -In self-managed Elasticsearch, you manage both of these certificates yourself. - -In {{eck}}, you can manage certificates for the HTTP layer. Certificates for the transport layer are managed by ECK and can’t be changed. However, you can set your own certificate authority, customize certificate contents, and provide your own certificate generation tools using transport settings. - -In {{ece}}, you can use one or more proxy certificates to secure the HTTP layer. These certificates are managed at the ECE installation level. Transport-level encryption is managed by ECE and certificates can’t be changed. -::: - -:::{tab-item} Comparative overviews II -:sync: three - -**Managed security in Elastic Cloud** - -Elastic Cloud has built-in security. For example, HTTPS communications between Elastic Cloud and the internet, as well as inter-node communications, are secured automatically, and cluster data is encrypted at rest. - -You can augment Elastic Cloud security features in the following ways: - -* Configure traffic filtering to prevent unauthorized access to your deployments. -* Encrypt your deployment with a customer-managed encryption key. -* Secure your settings with the Elasticsearch keystore. -* Allow or deny Cloud IP ranges using Elastic Cloud static IPs. - -[Learn more about security measures in Elastic Cloud](https://www.elastic.co/cloud/security). - -::: -:::: - - -## Sibling pages - -**Use case:** - -* Processes that have significant differences **across multiple procedures** -* Chained procedures where not all of the procedures are needed for all contexts / where the flow across procedures is muddied when versioning context is added -* Very complex pages that are already heavily using tabs and other tools we use for versioning differences, making it hard to add another “layer” of content -* Beta to GA transitions? Hide the beta doc and leave it linked to the GA doc, which will presumably be more stable? - -**Number to use:** As few as possible. Consider leveraging other ways of communicating versioning differences to reduce the number of sibling pages. - -**When to use:** - -When version differences are just too large to be handled with any of our other tools. Try to avoid creating sibling pages when you can. - -% Down the line, if we need to, we could easily convert version-sensitive sibling pages into “picker” pages - -### Examples - -[Cloud Hosted deployment billing dimensions](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization/billing/cloud-hosted-deployment-billing-dimensions) - -and its sibling - -[{{serverless-short}} project billing dimensions](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization/billing/serverless-project-billing-dimensions) diff --git a/docs/versions/index.md b/docs/versions/index.md deleted file mode 100644 index 1629c8053..000000000 --- a/docs/versions/index.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -navigation_title: "Versions and types" ---- - -# Documenting versions and deployment types - -:::{warning} -This documentation may be out of date. For updated guidance, refer to [](/contribute/cumulative-docs.md). -::: - -In Elastic Docs v3, we document features in a centralized place, regardless of the software version or deployment type it applies to. -For example, we might document the Serverless and Elastic Stack 9.0.0 implementations of a feature on a single page, and then use content patterns to highlight where prerequisites, options, or behaviors differ between these implementations. - -This approach improves our documentation in several ways: - -* When a user arrives in our documentation from an outside source, they'll be likelier to land on a page or section that applies to them. -* 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. -* Comparing and contrasting differences helps users to understand what is available to them, and improves awareness of the ways certain offerings might improve their experience. - -::::{note} -This page documents the first version of our approach to documenting differences in versions and deployment types, using our current technologies. -Our approach might change as additional documentation features become available. -:::: - -## Basic concepts and principles - -* [Versioning facets](#versioning-facets) -* [Defaults and hierarchy](#defaults-and-hierarchy) -* [Versions and lifecycle states](#versions-and-lifecycle-states) - -### Versioning facets -There are multiple facets to versioning that we need to consider: - -| Facet | Description | -| --- | --- | -| **Stack flavor** | The Elasticsearch or Kibana feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **{{stack}} ** | -| **Deployment type** | The way Elastic is deployed:

- **Serverless** (sometimes "Elastic Cloud Serverless")
- **Elastic Cloud Hosted**
- **Elastic Cloud on Kubernetes**
- **Elastic Cloud Enterprise**
- **Self-managed**

All deployment types other than **Serverless** are used to run a **{{stack}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. -| **Project type** | The Serverless project types where a feature can be used - either **Elasticsearch**, **Elastic Security**, or **Elastic Observability** | -| **Other versioning schemes** | Elastic products or tools with a versioned component, where stack versioning is not followed.

E.g. clients, Elastic Common Schema | - -% TODO: Final term for "Stack" -% TODO: Final term for "Self-managed" - -**How many facets do I need to use?** - -The role of these labels is providing a trust signal that the reader is viewing content that’s applicable to them. This means that the relevant labels should appear on all pages. However, we can choose to expose only one versioning facet on pages where only one facet is relevant: - -* Depending on what you're documenting, you might need to include information from multiple facets. For example, when relevant features exist at both the stack and the deployment level, both of these groups might be used together (e.g. security, user management, and trust features differ both at the deployment level and at the stack version level). - -* In some sections, such as **Explore and analyze**, features generally only differ by stack flavor. In these cases, you can choose to include only this facet on the page. - -### Defaults and hierarchy - -Do not assume a default deployment type, stack flavor, product version, or project type. - -Treat all flavors and deployment types equally. Don't treat one as the "base" and the other as the "exception". - -However, we should all display our flavors and versions in the same order for consistency. This order reflects organizational priorities. - -**Flavors:** - -1. Serverless -2. Stack - -**Deployment types:** - -1. Serverless -2. Elastic Cloud Hosted -3. Elastic Cloud on Kubernetes -4. Elastic Cloud Enterprise -5. Self-managed - -When it comes to hierarchy of versions, always put the newest version first. - -### Versions and lifecycle states - -In Elastic Docs v3, we currently document only our latest major versions (Elastic Stack 9.0.0, ECE 4.0.0 and later, ECK 3.0.0 and later). - -Add version labels only when a feature was added as part of the major version release (e.g. 9.0.0), or added in subsequent minor releases (e.g. 9.1.0). Do not add version information to features added before these releases. For example, features added in 8.16.0 don't need an 8.16.0 label or a 9.0.0 label, but features added in 9.0.0 need a 9.0.0 label. - -From the latest major version release onward, the entire feature lifecycle should be represented. This means that you need to add separate labels for the following states: - -* beta or technical preview -* GA -* deprecated -* removed - -We hope to simplify or consolidate these lifecycle labels in future. - -::::{warning} -This feature doesn't currently work - currently, only one label will appear. -:::: - -## Content patterns - -Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. - -Choose from: - -:::{include} _snippets/content-patterns-list.md -::: - -## Best practices - -### Screenshots - -Follow these principles to use screenshots in our unversioned documentation system: - -* Reduce screenshots when they don’t explicitly add value. -* When adding a screenshot, determine the minimum viable screenshot and whether it can apply to all relevant versions. -* Take and maintain screenshots for only the most recent version, with very few exceptions that should be considered on a case-by-case basis. -* In case of doubt, prioritize serverless.