diff --git a/docs/_docset.yml b/docs/_docset.yml index ff58f3263..d47bca378 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -13,6 +13,9 @@ subs: serverless-short: Serverless ece: "Elastic Cloud Enterprise" eck: "Elastic Cloud on Kubernetes" + ech: "Elastic Cloud Hosted" + serverless-full: "Elastic Cloud Serverless" + ecloud: "Elastic Cloud" features: primary-nav: false @@ -31,6 +34,8 @@ toc: - file: on-the-web.md - file: move.md - file: redirects.md + - file: cumulative-docs.md + - file: deployment-models.md - file: add-repo.md - folder: migration children: @@ -69,6 +74,7 @@ toc: - file: navigation.md - file: extensions.md - file: page.md + - file: deployment-models.md - folder: syntax children: - file: index.md diff --git a/docs/configure/deployment-models.md b/docs/configure/deployment-models.md new file mode 100644 index 000000000..c38e70c5a --- /dev/null +++ b/docs/configure/deployment-models.md @@ -0,0 +1,104 @@ +# Content sources + +To support multiple deployment models for different repositories, we support the concept of a content source. + +Next +: The source for the upcoming documentation. + +Current +: The source for the active documentation. + + +Our publish environments are connected to a single content source. + +| Publish Environment | Content Source | +|---------------------|----------------| +| Production | `Current` | +| Staging | `Current` | +| Edge | `Next` | + +This allows you as an owner of a repository to choose two different deployment models. + +## Deployment models + +The new documentation system supports 2 deployment models. + +Continuous deployment. +: This is the default where a repositories `main` or `master` branch is continuously deployed to production. + +Tagged deployment +: Allows you to 'tag' a single git reference (typically a branch) as `current` which will be used to deploy to production. + Allowing you to control the timing of when new documentation should go live. + + +### Continuous deployment + +This is the default. To get started, follow our [guide](/migration/guide/index.md) to set up the new docs folder structure and CI configuration. + +Once setup ensure the repository is added to our `assembler.yml` under `references`. + +For example say you want to onboard `elastic/my-repository` into the production build: + +```yaml +references: + my-repository: +``` + +Is equivalent to specifying. + +```yaml +references: + my-repository: + next: main + current: main +``` + +% TODO we need navigation.yml docs +Once the repository is added, its navigation still needs to be injected into to global site navigation. + +### Tagged deployment + +If you want to have more control over the timing of when your docs go live to production. Configure the repository +in our `assembler.yml` to have a fixed git reference (typically a branch) deploy the `current` content source to production. + +```yaml +references: + my-other-repository: + next: main + current: 9.0 +``` + +:::{note} +In order for `9.0` to be onboarded it needs to first follow our [migration guide](/migration/guide/index.md) and have our documentation CI integration setup. +Our CI integration checks will block until `current` is successfully configured +::: + +#### CI configuration + +To ensure [tagged deployments](#tagged-deployment) can be onboarded correctly, our CI integration needs to have appropriate `push` + branch triggers. + +```yml +name: docs-build + +on: + push: + branches: + - main + - '\d+.\d+' <1> + pull_request_target: ~ + merge_group: ~ + +jobs: + docs-preview: + uses: elastic/docs-builder/.github/workflows/preview-build.yml@main + with: + path-pattern: docs/** + permissions: + deployments: write + id-token: write + contents: read + pull-requests: write +``` + +1. Ensure version branches are built and publish their links ahead of time. \ No newline at end of file diff --git a/docs/contribute/_snippets/docs-intro.md b/docs/contribute/_snippets/docs-intro.md new file mode 100644 index 000000000..da6162298 --- /dev/null +++ b/docs/contribute/_snippets/docs-intro.md @@ -0,0 +1,5 @@ +elastic.co/docs uses our new build system, also known as "Docs V3", which uses an extended version of markdown as its markup language. Refer to our [syntax guide](/syntax/index.md) to learn more. + +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 diff --git a/docs/contribute/_snippets/guide-intro.md b/docs/contribute/_snippets/guide-intro.md new file mode 100644 index 000000000..73a24366f --- /dev/null +++ b/docs/contribute/_snippets/guide-intro.md @@ -0,0 +1,3 @@ +To contribute to elastic.co/guide, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses ASCIIDoc as its markup language. + +Docs for {{stack}} 8.x, {{ece}} 3.x, and {{eck}} 2.x can all be found on this site. \ No newline at end of file diff --git a/docs/contribute/_snippets/tag-processing.md b/docs/contribute/_snippets/tag-processing.md new file mode 100644 index 000000000..3c1003d41 --- /dev/null +++ b/docs/contribute/_snippets/tag-processing.md @@ -0,0 +1,17 @@ +`applies_to` tags are rendered as badges in the documentation output. They reproduce the "key + lifecycle status + version" indicated in the content sources. + +Specifically for versioned products, badges will display differently when the `applies_to` key specifies a product version that has not been released to our customers yet. + +* `Planned` (if the lifecycle is preview, beta, or ga) +* `Deprecation planned` (if the lifecycle is deprecated) +* `Removal planned` (if the lifecycle is removed) + +This is computed at build time (there is a docs build every 30 minutes). The documentation team tracks and maintains released versions for these products centrally. + +When multiple lifecycle statuses and versions are specified in the sources, several badges are shown. + +:::{note} +Visuals and wording in the output documentation are subject to changes and optimizations. +::: + +% todo: link to central config \ No newline at end of file diff --git a/docs/contribute/_snippets/tagged-warning.md b/docs/contribute/_snippets/tagged-warning.md new file mode 100644 index 000000000..c52f3b3ab --- /dev/null +++ b/docs/contribute/_snippets/tagged-warning.md @@ -0,0 +1,7 @@ +:::{warning} +Some repositories use a [tagged deployment model](/contribute/deployment-models.md), which means that their docs are published from a branch that is not `main` or `master`. In these cases, documentation changes need to be made to `main` or `master`, and then backported to the relevant branches. + +For detailed backporting guidance, refer to the example in [Choose the docs deployment model for a repository](/contribute/deployment-models.md#workflow-2-tagged-deployment). + +To determine the published branches for a repository, find the repository in [assembler.yml](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/assembler.yml). +::: diff --git a/docs/contribute/_snippets/two-systems.md b/docs/contribute/_snippets/two-systems.md new file mode 100644 index 000000000..3b70902ab --- /dev/null +++ b/docs/contribute/_snippets/two-systems.md @@ -0,0 +1,7 @@ +Because the new documentation site only hosts documentation for newer releases, the way that you contribute depends on the version that you want to document. + +For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs), refer to [Find docs for your product version](https://www.elastic.co/docs/get-started/versioning-availability#find-docs-for-your-product-version). Versions prior to the versions listed on that page are documented on our legacy system, [elastic.co/guide](https://www.elastic.co/guide). + +:::{tip} +Unversioned products, such as {{ech}} and {{serverless-full}}, are documented on [elastic.co/docs](https://www.elastic.co/docs). +::: diff --git a/docs/contribute/add-repo.md b/docs/contribute/add-repo.md index 4aab7410c..23007cd30 100644 --- a/docs/contribute/add-repo.md +++ b/docs/contribute/add-repo.md @@ -54,6 +54,10 @@ references: yadda-docs: ``` +:::{tip} +In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [deployment model](deployment-models.md). You might want to change your deployment model 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/src/tooling/docs-assembler/navigation.yml) file to add the repository to the navigation. For example, to add the `elastic/yadda-docs` repository under **Reference**: diff --git a/docs/contribute/cumulative-docs.md b/docs/contribute/cumulative-docs.md new file mode 100644 index 000000000..cd439a4c2 --- /dev/null +++ b/docs/contribute/cumulative-docs.md @@ -0,0 +1,134 @@ +# Write cumulative documentation + + + +In our markdown-based documentation system, we write docs cumulatively regardless of the [deployment model](deployment-models.md) selected. + +**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} +Nothing changes for our ASCIIDoc-based documentation system, that remains published and maintained for the following versions: Elastic Stack until 8.19, ECE until 3.8, ECK until 2.x, etc. +::: + +**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. + +This extends to deprecations and deletions: No information should be removed for supported product versions, unless it was never accurate. It can be refactored to improve clarity and flow, or to accommodate information for additional products, deployment types, and versions as needed. + +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). +* [When a feature goes into a new state as compared to the established base version](#tagging-version-related-changes-mandatory). + +This tagging system is mandatory for all of the public-facing documentation. We refer to it as “[applies_to](https://elastic.github.io/docs-builder/syntax/applies/)” tags or badges. + +## Tagging products and deployment models + +### 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. + +* The `applies_to` attribute is used to display contextual badges on each page. +* The `products` attribute is used by the search to let users filter their results when searching the docs. + + For the full list of supported keys and values, refer to [frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter). + + +:::{include} /syntax/_snippets/page-level-applies-examples.md +::: + +### Section or inline contexts (situational) + +When the context differs from what was specified at the page level in a specific section or part of the page, it is appropriate to re-establish it. For example: + +:::{include} /syntax/_snippets/section-level-applies-examples.md +::: + +* Likewise, when the difference is specific to just one paragraph or list item, the same rules apply. Just the syntax slightly differs so that it stays inline: + + :::{include} /syntax/_snippets/line-level-applies-example.md + ::: + +### 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**. +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: + + ```yml + --- + applies_to: + stack: ga + serverless: + elasticsearch: ga + security: ga + observability: unavailable + --- + ``` + + +* 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 + —-- + + # Spaces + + [...] + + ## Configure a space-level landing page [space-landing-page] + ```{applies_to} + stack: ga + serverless: unavailable + ``` + ```` +% I think we wanted to not specify stack here + +## 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](https://elastic.github.io/docs-builder/syntax/applies/) 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. +For this case, no specific version tagging is necessary. + +**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](deployment-models.md). + +We do not do date-based tagging for unversioned products. + +### For unversioned products (typically {{serverless-short}} and {{ech}}) + +:::{include} /syntax/_snippets/unversioned-lifecycle.md +::: + +### For versioned products + +:::{include} /syntax/_snippets/versioned-lifecycle.md +::: + +### Identify multiple states for the same content + +:::{include} /syntax/_snippets/multiple-lifecycle-states.md +::: + +## How do these tags behave in the output? + +:::{include} /contribute/_snippets/tag-processing.md +::: \ No newline at end of file diff --git a/docs/contribute/deployment-models.md b/docs/contribute/deployment-models.md new file mode 100644 index 000000000..db75748db --- /dev/null +++ b/docs/contribute/deployment-models.md @@ -0,0 +1,123 @@ +--- +navigation_title: Choose a deployment model +--- + +# Choose the docs deployment model for a repository + +With Docs V3 (elastic.co/docs), a single branch is published per repository. This branch is set to `main` (or `master`) by default. This is known as the continuous deployment model. However, it is possible to instead publish a different branch, also known as the tagged deployment model. + +On this page, you'll learn how to choose the right deployment model for your repository, and how to change the deployment model. You'll also learn about the workflows for working in each deployment model. + +## Why is `main` the default publication branch? + +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. +* 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. +* 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 `current` branch in order to be published on time. + +You **don't** need to change your deployment model to enable writing docs about future versions. Review the [continuous deployment workflow](#workflow-1-default-continuous-deployment) and [](cumulative-docs.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). + +## How to change the published branch + +Choosing to switch between publishing docs from `main` and publishing docs from a version branch is a long-term decision. This decision impacts all docs for an entire repository. Reach out to the docs team to discuss the change. + +After it has been established that a repository should publish from a version branch rather than `main`: + +1. In the [docs assembler file](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/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. +2. [Add new triggers to the `docs-build` CI integration](/configure/deployment-models.md#ci-configuration). +3. 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`. +4. When these releases happen, create a PR against the [assembler file](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/assembler.yml) that defines the new `current` branch, to merge on release day. + +For more information, refer to [](/configure/deployment-models.md). + +## Workflow 1 (default): Continuous deployment + +Learn how to make updates in the continuous deployment model, where the repo is publishing docs from `main`. + +### Where to make docs changes [make-changes-cd] + +Initiate the changes by opening a PR against the `main` branch of the repo. + +### How to write those changes [write-changes-cd] + +In our markdown-based documentation system, we [write docs cumulatively](cumulative-docs.md) regardless of the publication model selected. + +### Merging and backporting [merge-backport-cd] + +When a repo publishes docs from its `main` branch, any merged changes are published within 30 minutes. It is then very important to consider the timing of the merge depending on the documented product: + +| | 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`. | + +When a repo is publishing docs from its `main` branch, no backporting is needed. + +:::{tip} +If you don’t want to hold on too many PRs to publish on release day, merge them to a feature branch, so you only have to merge this feature branch to `main` on release day. +::: + +### More examples [more-examples-cd] + +We’ve prepared a few end-to-end examples to help in [Figma](https://www.figma.com/design/CZDl0szuGsQfJhFpnwJVWS/Applies_to-Docs-V3?node-id=0-1&p=f&t=lBPrvde0k5zg9U0E-0). + +## Workflow 2: Tagged deployment + +Learn how to make updates in the continuous deployment model, where the repo is publishing docs from a specific `version` branch. + +### Where to make docs changes [make-changes-td] + +Initiate the changes by opening a PR against the `main` branch of the repo. The changes will be backported to the relevant version branches as detailed below. + +### How to write those changes [write-changes-td] + +In our markdown-based documentation system, we [write docs cumulatively](cumulative-docs.md) regardless of the publication model selected. + +### Merging and backporting [merge-backport-td] + +When a repo publishes docs from a version branch, there is no timing constraint to merge the initial PR against the `main` branch. If `main` is set as your `next` branch, then the docs changes become visible on the internal staging docs site at [staging-website.elastic.co/docs](http://staging-website.elastic.co/docs). Otherwise, the docs changes become visible on the internal staging docs site when you backport to your `next` branch. + +The changes must then be backported to their relevant version branches, and no further back than the branch set as `current` for the documentation publication system: + +| | 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`. | + +#### 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 [docs assembler](https://github.com/elastic/docs-builder/blob/625e75b35841be938a8df76a62deeee811ba52d4/src/tooling/docs-assembler/assembler.yml#L70) 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} +While you *can* backport to versions prior to the `current` version when applicable to maintain parity between the code and the docs on a given branch, that content will not be used in the current state of the docs. +::: + +### More examples [more-examples-td] + +We’ve prepared a few end-to-end examples to help in [Figma](https://www.figma.com/design/CZDl0szuGsQfJhFpnwJVWS/Applies_to-Docs-V3?node-id=0-1&p=f&t=lBPrvde0k5zg9U0E-0). diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 8ee3a794d..f41eedc0b 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -10,52 +10,42 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi ## Contribute to the docs [#contribute] -The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. +In April 2025, we released our new documentation site. This site includes documentation for our latest product versions, including {{stack}} 9.0+ and {{serverless-full}}. -### Contribute to Elastic Stack version 8.x docs and earlier +:::{include} _snippets/two-systems.md +::: -To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses AsciiDoc as it's authoring format. +### Contribute to elastic.co/guide -* For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) -* For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) +:::{include} _snippets/guide-intro.md +::: -### Contribute to Elastic Stack version 9.0 docs and later +* For **simple bug fixes and enhancements**: [Contribute on the web](on-the-web.md) +* For **complex or multi-page updates**: See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) -* For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md) -* For **complex or multi-page updates** --> [Contribute locally](locally.md) +### Contribute elastic.co/docs -Starting with Elastic Stack version 9.0, ECE 4.0, and ECK 3.0, a new set of docs is no longer published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content using a [cumulative approach](#cumulative-docs). +:::{include} _snippets/docs-intro.md +::: -#### Write cumulative documentation [#cumulative-docs] +* For **simple bug fixes and enhancements**: [Contribute on the web](on-the-web.md) +* For **complex or multi-page updates**: [Contribute locally](locally.md) -Cumulative documentation means that one page can cover multiple product versions, deployment types, and release stages. Instead of creating separate pages for each release, we update the same page with version-specific details. +#### Branches in V3 -This helps readers understand which parts of the content apply to their own ecosystem and product versions, without needing to switch between different versions of a page. +In Docs V3, a single branch is published per repository. This branch is set to `main` (or `master`) 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. -Following this approach, information for supported versions must not be removed unless it was never accurate. Instead, refactor the content to improve clarity or to include details for other products, deployment types, or versions. - -In order to achieve this, the markdown source files integrate a **tagging system** meant to identify: - -* Which Elastic products and deployment models the content applies to. -* When a feature goes into a new state as compared to the established base version. - -This [tagging system](#applies-to) is mandatory for all of the public-facing documentation. - -##### The `applies_to` tag [#applies-to] - -Use the [`applies_to`](../syntax/applies.md) tag to indicate which versions, deployment types, or release stages each part of the content is relevant to. - -You must always use the `applies_to` tag at the [page](../syntax/applies.md#page-annotations) level. Optionally, you can also use it at the [section](../syntax/applies.md#section-annotations) or [inline](../syntax/applies.md#inline-annotations) level if certain parts of the content apply only to specific versions, deployment types, or release stages. +[Learn more about deployment models](deployment-models.md). ## Report a bug -* It's a **documentation** problem --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md) -* It's a **build tool (docs-builder)** problem --> [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml) +* It's a **documentation** problem: [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md). You can open sensitive issues in our [internal repo](https://github.com/elastic/docs-content-internal/issues/new/choose). +* It's a **build tool (docs-builder)** problem: [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml) -## Request an enhancement +## Request an enhancement or documentation for a new feature -* Make the **documentation** better --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) -* Make our **build tool (docs-builder)** better --> [Start a docs-builder discussion](https://github.com/elastic/docs-builder/discussions) +* Make the **documentation** better: [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml). You can open sensitive issues in our [internal repo](https://github.com/elastic/docs-content-internal/issues/new/choose). +* Make our **build tool (docs-builder)** better: [Start a docs-builder discussion](https://github.com/elastic/docs-builder/discussions) ## Work on docs-builder diff --git a/docs/contribute/locally.md b/docs/contribute/locally.md index bcbe30299..d682ce772 100644 --- a/docs/contribute/locally.md +++ b/docs/contribute/locally.md @@ -49,7 +49,7 @@ This guide uses the first option. If you'd like to clone the repository and buil 2. **Run docs-builder from a docs folder** - Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000: + Use the `serve` command from any docs folder to start serving the documentation at [http://localhost:3000](http://localhost:3000): ```sh docs-builder serve @@ -83,7 +83,7 @@ If you get a `Permission denied` error, make sure that you aren't trying to run 2. **Run docs-builder from a docs folder** - Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000: + Use the `serve` command from any docs folder to start serving the documentation at [http://localhost:3000](http://localhost:3000): ```sh docs-builder serve @@ -93,19 +93,19 @@ If you get a `Permission denied` error, make sure that you aren't trying to run :::: -## Clone a content repository [#step-two] +## Step 2: Clone a content repository [#step-two] :::{tip} -Documentation lives in many repositories across Elastic. If you're unsure which repository to clone, you can use the "Edit this page" link on any documentation page to determine where the source file lives. +Documentation is hosted in many repositories across Elastic. If you're unsure which repository to clone, you can use the **Edit this page** link on any documentation page to determine where the source file is hosted. ::: -In this guide, we'll clone the [`docs-content`](https://github.com/elastic/docs-content) repository. The `docs-content` repository is the home for narrative documentation at Elastic. Clone this repo to a directory of your choice: +In this guide, we'll clone the [`docs-content`](https://github.com/elastic/docs-content) repository. The `docs-content` repository is the home for most narrative documentation at Elastic. Clone this repo to a directory of your choice: ```sh git clone https://github.com/elastic/docs-content.git ``` -## Serve the documentation [#step-three] +## Step 3: Serve the documentation [#step-three] Static-site generators like docs-builder can serve docs locally. This means you can edit the source and see the result in the browser in real time. @@ -122,7 +122,7 @@ cd docs-content :::::{step} Run docs-builder -Run the `docs-builder` binary with the `serve` command to build and serve the content set to http://localhost:3000. If necessary, specify the path to the `docset.yml` file that you want to build with `-p`. +Run the `docs-builder` binary with the `serve` command to build and serve the content set to [http://localhost:3000](http://localhost:3000). If necessary, specify the path to the `docset.yml` file that you want to build with `-p`. For example: @@ -145,7 +145,7 @@ docs-builder serve -p .\migration-test ::::: :::::{step} Open the documentation in the browser -Now you should be able to view the documentation locally by navigating to http://localhost:3000. +Now you should be able to view the documentation locally by navigating to [http://localhost:3000](http://localhost:3000). ::::: :::::: @@ -153,6 +153,11 @@ Now you should be able to view the documentation locally by navigating to http:/ We write docs in Markdown. Refer to our [syntax](../syntax/index.md) guide for the flavor of Markdown that 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). + +:::{include} _snippets/tagged-warning.md +::: + ## Step 5: Push your changes [#step-five] After you've made your changes locally: @@ -160,7 +165,7 @@ After you've made your changes locally: * [Push your commits](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository) * [Open a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) -## Step 5: View the preview +## Step 6: View the preview You can open a docs preview from the Deployments page of the repository. For example, [https://github.com/elastic/docs-content/deployments](https://github.com/elastic/docs-content/deployments). diff --git a/docs/contribute/on-the-web.md b/docs/contribute/on-the-web.md index a98750e71..deb3f543b 100644 --- a/docs/contribute/on-the-web.md +++ b/docs/contribute/on-the-web.md @@ -2,51 +2,58 @@ This section will help you understand how to update and contribute to our documentation post-migration. -## **Updating Documentation** +## Updating documentation -Depending on the version that your update impacts you may need to take different steps. +:::{include} _snippets/two-systems.md +::: -### **Update content for Version 8.x and earlier** [update-content-for-version-8.x-and-earlier] +### Update elastic.co/guide [guide] -For content that is related to 8.x, these changes should be done in the original source folders in their respective repositories. Here’s how you can do it: +:::{include} _snippets/guide-intro.md +::: -1. Navigate to the page that is impacted -2. Click the **edit** button -3. Ensure the targeted branch is \ +These changes should be made in the original source folders in their respective repositories. Here’s how you can do it: + +1. Navigate to the page that is impacted. +2. Click the **Edit** button. +3. Ensure the targeted branch is \. 4. Make the necessary updates. 5. Commit your changes and create a pull request. 6. Add the appropriate labels per repo as found at [Page: Working across docs repos](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/61604182/Working+across+docs+repos) -Note: If you are working in a repo like Kibana or the cloud repo where backports can be complicated. You can use the [backport tool](https://github.com/sorenlouv/backport) to manage your backport. +:::{note} +If you are working in a repo like Kibana or the cloud repo, backports can be complicated. You can use the [backport tool](https://github.com/sorenlouv/backport) to manage your backport. +::: + +### Update elastic.co/docs [docs] -### **Update content for Version 9.0 and later** [update-content-for-version-9.0-and-later] +:::{include} _snippets/docs-intro.md +::: -For content related to version 9.0 and future versions, updates should be made in the [`docs-content`](https://github.com/elastic/docs-content) repository. Follow these steps to ensure your contributions are correctly made: +For content hosted on elastic.co/docs, most conceptual and narrative content is stored in the [`docs-content`](https://github.com/elastic/docs-content) repository, and most reference content is hosted in the relevant product's repository. Follow these steps to ensure your contributions are correctly made: -1. Navigate to the page that is impacted +1. Navigate to the page that is impacted. 2. Click the **Edit** button. 3. Identify the section that requires updates. 4. Make the necessary updates. 5. Commit your changes and create a pull request. +:::{include} _snippets/tagged-warning.md +::: -## **What if I need to update both 8.x and 9.x docs?** +## What if I need to update docs in both systems? -If you need to merge changes that relate to version 8.x to the 9.0 and later documentation it is recommended to update the 9.x documentation first in markdown. Then you can convert the updates to asciidoc and make the changes to the 8.x documentation. To do this, follow these steps: +If you need to merge changes that are published in both systems (usually because a change is valid in multiple product versions, such as stack 9.x and 8.x) it is recommended to update the documentation in elastic.co/docs first. Then you can convert the updates to ASCIIDoc and make the changes to the elastic.co/guide documentation. To do this, follow these steps: 1. Install [pandoc](https://pandoc.org/installing.html) to convert your markdown file to asciidoc -2. Update the content 9.x first in markdown as described in [Version 9.0 and Later](#update-content-for-version-9.0-and-later) in the [`docs-content`](https://github.com/elastic/docs-content) repository -3. Run your changes through pandoc - 1. If you need to bring over the entire file you can run the following command and it will create an asciidoc file for you. `pandoc -f gfm -t asciidoc ./.md -o .asciidoc` +2. Update the /docs content first in markdown as described in [Update elastic.co/docs](#docs) in the relevant repository. +3. Run your changes through pandoc: + 1. If you need to bring over the entire file, you can run the following command and it will create an asciidoc file for you. `pandoc -f gfm -t asciidoc ./.md -o .asciidoc` 2. If you just need to port a specific section you can use: `pandoc -f gfm -t asciidoc ./.md` and the output of the file will be in your command window from which you can copy. -4. Follow the steps in [Update content for Version 8.x and earlier](#update-content-for-version-8.x-and-earlier) to publish your changes. -5. If the change is too large or complicated, create a new issue in the [`docs-content`](https://github.com/elastic/docs-content) repository detailing the changes made for the team to triage. -6. Merge the changes and close the issue once the updates are reflected in the [`docs-content`](https://github.com/elastic/docs-content) repository. - -## **Migration Considerations** - -During the migration, content may be moved around, and there won't be a 1-to-1 mapping between old and new locations. This means updates may need to be applied in multiple places. If your changes affect version 8.x content, consider merging those changes in the 9.x content first and then add it to the appropriate 8.x content. If you have any issues create an issue in the [`docs-content`](https://github.com/elastic/docs-content) repository. +4. Follow the steps in [Update elastic.co/guide](#guide) to publish your changes. +5. If the change is too large or complicated, create a new issue in the [`docs-content`](https://github.com/elastic/docs-content) or [`docs-content-internal`](https://github.com/elastic/docs-content-internal) repository detailing the changes made for the team to triage. +6. Merge the changes and close the issue once the updates are reflected in the documentation. -% To be added “Kibana and Cloud repository instructions. You need to target main to backport. Changes in main will be lost and you need to recreate it in the new architecture after the freeze is over. +## Migration considerations -% Need a good category mapping across the content .. not to the file level for area level +During the migration, content may be moved around, and there won't be a 1-to-1 mapping between old and new locations. This means updates may need to be applied in multiple places. If your changes affect /guide content, consider merging those changes in the /docs content first and then add it to the appropriate /guide content. If you have any issues, create an issue in the [`docs-content`](https://github.com/elastic/docs-content) or [`docs-content-internal`](https://github.com/elastic/docs-content-internal) repository. \ No newline at end of file diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md index 46a40bfe6..a1d9201c6 100644 --- a/docs/migration/versioning.md +++ b/docs/migration/versioning.md @@ -4,113 +4,20 @@ As part of the new information architecture, pages with varying versioning schem To ensure a seamless experience for users and contributors, the new versioning approach adheres to the following: -* 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. 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. -* 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. +* **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). -For versioning plan details, check [Docs Versioning plan](https://docs.google.com/presentation/d/1rHl0ia0ZkLHPLAYE5522CTDoatqwAxwAo29_etStPW8/edit?usp=sharing). To learn how to call out versioning differences in docs-builder, see [product availability](../syntax/applies.md). +## Tag processing - -## Content Sources - -To support multiple deployment models for different repositories, we support the concept of a content source. - -Next -: The source for the upcoming documentation. - -Current -: The source for the active documentation. - - -Our publish environments are connected to a single content source. - -| Publish Environment | Content Source | -|---------------------|----------------| -| Production | `Current` | -| Staging | `Current` | -| Edge | `Next` | - -This allows you as an owner of a repository to choose two different deployment models. - -## Deployment models. - -The new documentation system supports 2 deployment models. - -Continuous deployment. -: This is the default where a repositories `main` or `master` branch is continuously deployed to production. - -Tagged deployment -: Allows you to 'tag' a single git reference (typically a branch) as `current` which will be used to deploy to production. - Allowing you to control the timing of when new documentation should go live. - - -### Continuous Deployment - -This is the default. To get started, follow our [guide](guide/index.md) to set up the new docs folder structure and CI configuration - -Once setup ensure the repository is added to our `assembler.yml` under `references`. - -For example say you want to onboard `elastic/my-repository` into the production build: - -```yaml -references: - my-repository: -``` - -Is equivalent to specifying. - -```yaml -references: - my-repository: - next: main - current: main -``` - -% TODO we need navigation.yml docs -Once the repository is added, its navigation still needs to be injected into to global site navigation. - -### Tagged Deployment - -If you want to have more control over the timing of when your docs go live to production. Configure the repository -in our `assembler.yml` to have a fixed git reference (typically a branch) deploy the `current` content source to production. - -```yaml -references: - my-other-repository: - next: main - current: 9.0 -``` - -:::{note} -In order for `9.0` to be onboarded it needs to first follow our [migration guide](guide/index.md) and have our documentation CI integration setup. -Our CI integration checks will block until `current` is successfully configured +:::{include} /contribute/_snippets/tag-processing.md ::: -#### CI Configuration - -To ensure [tagged deployments](#tagged-deployment) can be onboarded correctly, our CI integration needs to have appropriate `push` - branch triggers. - -```yml -name: docs-build - -on: - push: - branches: - - main - - '\d+.\d+' <1> - pull_request_target: ~ - merge_group: ~ +## Deployment models -jobs: - docs-preview: - uses: elastic/docs-builder/.github/workflows/preview-build.yml@main - with: - path-pattern: docs/** - permissions: - deployments: write - id-token: write - contents: read - pull-requests: read -``` +In Docs V3, a single branch is published per repository. This branch is set to `main` (or `master`) 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. -1. Ensure version branches are built and publish their links ahead of time. \ No newline at end of file +* [Learn how to choose the right deployment model for your repository](/contribute/deployment-models.md) +* [Learn how to set up your selected deployment model](/configure/deployment-models.md) \ No newline at end of file diff --git a/docs/syntax/_snippets/line-level-applies-example.md b/docs/syntax/_snippets/line-level-applies-example.md new file mode 100644 index 000000000..9bb75ce0b --- /dev/null +++ b/docs/syntax/_snippets/line-level-applies-example.md @@ -0,0 +1,7 @@ +````markdown +**Spaces** let you organize your content and users according to your needs. + +- Each space has its own saved objects. +- {applies_to}`stack: ga` {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. +```` +% I think we wanted to not specify stack here diff --git a/docs/syntax/_snippets/multiple-lifecycle-states.md b/docs/syntax/_snippets/multiple-lifecycle-states.md new file mode 100644 index 000000000..bb0bedf40 --- /dev/null +++ b/docs/syntax/_snippets/multiple-lifecycle-states.md @@ -0,0 +1,18 @@ +`applies_to` keys accept comma-separated values to specify lifecycle states for multiple product versions. For example: + +* A feature is added in 9.1 as tech preview and becomes GA in 9.4: + + ```yml + applies_to: + stack: preview 9.1, ga 9.4 + ``` + + +* A feature is deprecated in ECE 4.0 and is removed in 4.8. At the same time, it has already been removed in {{ech}}: + + ```yml + applies_to: + deployment: + ece: deprecated 4.0, removed 4.8 + ess: removed + ``` \ No newline at end of file diff --git a/docs/syntax/_snippets/page-level-applies-examples.md b/docs/syntax/_snippets/page-level-applies-examples.md new file mode 100644 index 000000000..b15e6c9c4 --- /dev/null +++ b/docs/syntax/_snippets/page-level-applies-examples.md @@ -0,0 +1,73 @@ +There are 3 typical scenarios to start from: + +* The documentation set or page is primarily about using or interacting with Elastic Stack components or the Serverless UI: + + ```yml + --- + applies_to: + stack: ga + serverless: ga + products: + - id: kibana + - id: elasticsearch + - id: elastic-stack + --- + ``` + +* The documentation set or page is primarily about orchestrating, deploying or configuring an installation (only include relevant keys): + + ```yml + --- + applies_to: + serverless: ga + deployment: + ess: ga + ece: ga + eck: ga + products: + - id: cloud-serverless + - id: cloud-hosted + - id: cloud-enterprise + - id: cloud-kubernetes + --- + + ``` + +* The documentation set or page is primarily about a product following its own versioning schema: + + ```yml + --- + applies_to: + product: ga + products: + - id: edot-collector + --- + ``` + % changing soon + +It can happen that it’s relevant to identify several or all of these dimensions for a page. Use your own judgement and check existing pages in similar contexts. + +```yml +--- +applies_to: + stack: ga + serverless: ga + deployment: + ess: ga + ece: ga + eck: ga +products: + - id: kibana + - id: elasticsearch + - id: elastic-stack + - id: cloud-serverless + - id: cloud-hosted + - id: cloud-enterprise + - id: cloud-kubernetes +--- +``` +% I don't know what this example is supposed to show + + + + diff --git a/docs/syntax/_snippets/section-level-applies-examples.md b/docs/syntax/_snippets/section-level-applies-examples.md new file mode 100644 index 000000000..00b5f14c1 --- /dev/null +++ b/docs/syntax/_snippets/section-level-applies-examples.md @@ -0,0 +1,41 @@ +* The whole page is generally applicable to {{stack}} 9.0 and to {{serverless-short}}, but one specific section isn’t applicable to {{serverless-short}} (and there is no alternative for it): + + ````md + --- + applies_to: + stack: ga + serverless: ga + --- + + # Spaces + + [...] + + ## Configure a space-level landing page [space-landing-page] + ```{applies_to} + stack: ga + serverless: unavailable + ``` + ```` + % I think we wanted to not specify stack here + +* The whole page is generally applicable to all deployment types, but one specific paragraph only applies to {{ech}} and {{serverless-short}}, and another paragraph only applies to {{ece}}: + + ````md + ## Cloud organization level security [cloud-organization-level] + ```{applies_to} + deployment: + ess: ga + serverless: ga + ``` + + [...] + + ## Orchestrator level security [orchestrator-level] + ```{applies_to} + deployment: + ece: ga + ``` + + [...] + ```` \ No newline at end of file diff --git a/docs/syntax/_snippets/unversioned-lifecycle.md b/docs/syntax/_snippets/unversioned-lifecycle.md new file mode 100644 index 000000000..52ac727a5 --- /dev/null +++ b/docs/syntax/_snippets/unversioned-lifecycle.md @@ -0,0 +1,33 @@ +Unversioned products don't follow a fixed versioning scheme and are released a lot more often than versioned products. All users are using the same version of this product. +* When a change is released in `ga`, it **doesn’t need any specific tagging**. +* When a change is introduced as preview or beta, use `preview` or `beta` as value for the corresponding key within the `applies_to`: + + ``` + --- + applies_to: + serverless: preview + --- + ``` +* When a change introduces a deprecation, use deprecated as value for the corresponding key within the `applies_to`: + + ``` + --- + applies_to: + deployment: + ess: deprecated + --- + ``` + +* When a change removes a feature, **remove the content**. + + **Exception:** If the content also applies to another context (for example a feature is removed in both Kibana 9.x and Serverless), then it must be kept for any user reading the page that may be using a version of Kibana prior to the removal. + + For example: + + ``` + --- + applies_to: + stack: deprecated 9.1, removed 9.4 + serverless: removed + --- + ``` \ No newline at end of file diff --git a/docs/syntax/_snippets/versioned-lifecycle.md b/docs/syntax/_snippets/versioned-lifecycle.md new file mode 100644 index 000000000..ae6af6fee --- /dev/null +++ b/docs/syntax/_snippets/versioned-lifecycle.md @@ -0,0 +1,36 @@ +* When a change is released in `ga`, users need to know which version the feature became available in: + + ``` + --- + applies_to: + stack: ga 9.3 + --- + ``` + +* When a change is introduced as preview or beta, use `preview` or `beta` as value for the corresponding key within the `applies_to`: + + ``` + --- + applies_to: + stack: beta 9.1 + --- + ``` + +* When a change introduces a deprecation, use `deprecated` as value for the corresponding key within the `applies_to`: + + ``` + --- + applies_to: + deployment: + ece: deprecated 4.2 + --- + ``` + +* When a change removes a feature, any user reading the page that may be using a version of Kibana prior to the removal must be aware that the feature is still available to them. For that reason, we do not remove the content, and instead mark the feature as removed: + + ``` + --- + applies_to: + stack: deprecated 9.1, removed 9.4 + --- + ``` \ No newline at end of file diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index b15cbe01c..c5f5cb8a2 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,6 +1,11 @@ # Applies to -Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a [cumulative approach](../contribute/index.md#cumulative-docs): 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.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: * Which Elastic products and deployment models the content applies to. @@ -8,6 +13,11 @@ To support this, source files use a tagging system to indicate: This is what the `applies_to` metadata is for. It can be used at the page, section, or inline level to specify applicability with precision. +## `applies_to` tags in the output + +:::{include} /contribute/_snippets/tag-processing.md +::: + ## When and where to use `applies_to` The `applies_to` metadata can be added at different levels in the documentation: @@ -16,7 +26,7 @@ The `applies_to` metadata can be added at different levels in the documentation: * [Section-level](#section-annotations) annotations allow you to specify different applicability for individual sections when only part of a page varies between products or versions. * [Inline](#inline-annotations) annotations allow fine-grained annotations within paragraphs or definition lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. -### Do’s and don’ts +### Dos and don’ts ✅ Use `applies_to` tags when features change state (`preview`, `beta`, `ga`, `deprecated`, `removed`) or when availability differs across deployments and environments. @@ -30,6 +40,8 @@ The `applies_to` metadata can be added at different levels in the documentation: ❌ 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). + ## Syntax The `applies_to` metadata supports an [exhaustive list of keys](#structured-model). @@ -38,18 +50,18 @@ When you write or edit documentation, only specify the keys that apply to that c Each key accepts values with the following syntax: ``` -: [version] +: [version] ``` Where: -- The [life-cycle](#life-cycle) is mandatory +- The [lifecycle](#lifecycle) is mandatory - The [version](#version) is optional - You can specify multiple states by separating them with a comma. For example: `stack: preview 9.1, ga 9.4` Note that a key without any value doesn't show any badge in the output. -### Life cycle +### Lifecycle `applies_to` accepts the following lifecycle states: @@ -86,138 +98,28 @@ applies_to: ### Lifecycle examples #### Unversioned products -Unversioned products don't follow a fixed versioning scheme and are released a lot more often than versioned products. All users are using the same version of this product. -* When a change is released in `ga`, it **doesn’t need any specific tagging**. -* When a change is introduced as preview or beta, use `preview` or `beta` as value for the corresponding key within the `applies_to`: - - ``` - --- - applies_to: - serverless: preview - --- - ``` -* When a change introduces a deprecation, use deprecated as value for the corresponding key within the `applies_to`: - - ``` - --- - applies_to: - deployment: - ess: deprecated - --- - ``` - -* When a change removes a feature, remove the content. -**Exception:** If the content also applies to another context (for example a feature is removed in both Kibana 9.x and Serverless), then it must be kept for any user reading the page that may be using a version of Kibana prior to the removal. For example: - - ``` - --- - applies_to: - stack: deprecated 9.1, removed 9.4 - serverless: removed - --- - ``` - -#### Versioned products - -* When a change is released in `ga`, users need to know which version the feature became available in: - - ``` - --- - applies_to: - stack: ga 9.3 - --- - ``` -* When a change is introduced as preview or beta, use `preview` or `beta` as value for the corresponding key within the `applies_to`: - - ``` - --- - applies_to: - stack: beta 9.1 - --- - ``` - -* When a change introduces a deprecation, use `deprecated` as value for the corresponding key within the `applies_to`: - - ``` - --- - applies_to: - deployment: - ece: deprecated 4.2 - --- - ``` +:::{include} _snippets/unversioned-lifecycle.md +::: -* When a change removes a feature, any user reading the page that may be using a version of Kibana prior to the removal must be aware that the feature is still available to them. For that reason, we do not remove the content, and instead mark the feature as removed: +#### Versioned products - ``` - --- - applies_to: - stack: deprecated 9.1, removed 9.4 - --- - ``` +:::{include} _snippets/versioned-lifecycle.md +::: #### Identify multiple states for the same content -A feature is deprecated in ECE 4.0 and is removed in 4.8. At the same time, it has already been removed in Elastic Cloud Hosted: - -``` ---- -applies_to: - deployment: - ece: deprecated 4.0, removed 4.8 - ess: removed ---- -``` +:::{include} /syntax/_snippets/multiple-lifecycle-states.md +::: ### Page annotations -All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use YAML frontmatter to indicate each deployment targets availability and lifecycle status. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). +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. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). #### Page annotation examples -There are 3 typical scenarios to start from: -1. The documentation set or page is primarily about using or interacting with Elastic Stack components or the Serverless UI: - - ```yaml - --- - applies_to: - stack: ga - serverless: ga - products: - - id: kibana - - id: elasticsearch - - id: elastic-stack - --- - ``` - -2. The documentation set or page is primarily about orchestrating, deploying or configuring an installation (only include relevant keys): - - ```yaml - --- - applies_to: - serverless: ga - deployment: - ess: ga - ece: ga - eck: ga - products: - - id: cloud-serverless - - id: cloud-hosted - - id: cloud-enterprise - - id: cloud-kubernetes - --- - ``` - -3. The documentation set or page is primarily about a product following its own versioning schema: - - ```yaml - --- - applies_to: - product: ga - products: - - id: edot-collector - --- - ``` +:::{include} _snippets/page-level-applies-examples.md +::: ### Section annotations @@ -263,54 +165,8 @@ This will allow the YAML inside the `{applies_to}` directive to be fully highlig #### Section annotation examples -1. The whole page is generally applicable to Elastic Stack 9.0 and to Serverless, but one specific section isn’t applicable to Serverless (and there is no alternative for it): - - ````markdown - ## Configure a space-level landing page [space-landing-page] - ```{applies_to} - stack: ga - serverless: unavailable - ``` - ```` - -2. The whole page is generally applicable to Elastic Cloud Enterprise and Elastic Cloud Hosted, but one specific paragraph only applies to Elastic Cloud Enterprise, and another paragraph explains the same, but for Elastic Cloud Hosted: - - ````markdown - ## Secure a deployment [secure-deployment-ech] - ```{applies_to} - deployment: - ess: ga - ``` - - [...] - - ## Secure a deployment [secure-deployment-ece] - ```{applies_to} - deployment: - ece: ga - ``` - - [...] - ```` -3. 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: - - ````markdown - --- - applies_to: - stack: ga - serverless: ga - --- - - # Spaces - - [...] - - ## Configure a space-level landing page [space-landing-page] - ```{applies_to} - stack: ga - serverless: unavailable - ``` - ```` +:::{include} _snippets/section-level-applies-examples.md +::: ### Inline annotations @@ -324,17 +180,13 @@ An inline version example would be {applies_to}`stack: beta 9.1` this allows you #### Inline annotation examples -1. The whole page is generally applicable to Elastic Stack 9.0 and to Serverless, but one specific section isn’t applicable to Serverless (and there is no alternative): - - ````markdown - **Spaces** let you organize your content and users according to your needs. +* The whole page is generally applicable to Elastic Stack 9.0 and to Serverless, but one specific section isn’t applicable to Serverless (and there is no alternative): - - Each space has its own saved objects. - - {applies_to}`stack: ga` {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. - ```` + :::{include} _snippets/line-level-applies-example.md + ::: -A specialized `{preview}` role exist to quickly mark something as a technical preview. It takes a required version number -as argument. +A specialized `{preview}` role exists to quickly mark something as a technical preview. It takes a required version number +as an argument. ```markdown Property {preview}`` @@ -363,4 +215,3 @@ applies_to: product: --- ``` -This allows you to annotate various facets as defined in [](../migration/versioning.md) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 681713b48..64f30caf6 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -4,6 +4,10 @@ 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: diff --git a/docs/versions/index.md b/docs/versions/index.md index 4b51c02b9..1629c8053 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -4,6 +4,10 @@ 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.