From ab7465746f18199f9a434b90a75a9eb1f75db69f Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 24 Jun 2025 17:34:37 -0400 Subject: [PATCH 01/12] draft --- docs/_docset.yml | 7 + docs/configure/deployment-models.md | 104 ++++++ docs/contribute/index.md | 49 ++- docs/contribute/releasing.md | 1 + docs/contribute/versioning/cumulative-docs.md | 307 ++++++++++++++++++ .../versioning/deployment-models.md | 107 ++++++ docs/migration/versioning.md | 118 +------ 7 files changed, 567 insertions(+), 126 deletions(-) create mode 100644 docs/configure/deployment-models.md create mode 100644 docs/contribute/releasing.md create mode 100644 docs/contribute/versioning/cumulative-docs.md create mode 100644 docs/contribute/versioning/deployment-models.md diff --git a/docs/_docset.yml b/docs/_docset.yml index 1d102f175..4b245299d 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -31,6 +31,12 @@ toc: - file: on-the-web.md - file: move.md - file: redirects.md + - folder: versioning + children: + - file: index.md + - file: deployment-models.md + - file: cumulative-docs.md + - file: releasing.md - folder: migration children: - file: index.md @@ -68,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..3bba8e11c --- /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](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 +::: + +#### 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: read +``` + +1. Ensure version branches are built and publish their links ahead of time. \ No newline at end of file diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 8ee3a794d..b02bbe231 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -10,52 +10,51 @@ 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 +The way that you contribute to the docs depends on the product version. -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. +For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs), refer to [Find docs for your product version](/get-started/versioning-availability.md#find-docs-for-your-product-version). Versions previous to the versions listed on that page are documented on our legacy system, [elastic.co/guide](https://www.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) +:::{tip} +Unversioned products, such as {{ech}} and {{serverless-full}}, are documented on [elastic.co/docs](https://www.elastic.co/docs). +::: -### Contribute to Elastic Stack version 9.0 docs and later +### Contribute to elastic.co/guide -* For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md) -* For **complex or multi-page updates** --> [Contribute locally](locally.md) +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. -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). +Docs for {{stack}} 8.x, {{ece}} 3.x, and {{eck}} 2.x can all be found on this site. -#### 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**: See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) -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. +### Contribute elastic.co/docs -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. +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.md) to learn more. -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. +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. -In order to achieve this, the markdown source files integrate a **tagging system** meant to identify: +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). -* 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. +* For **simple bug fixes and enhancements**: [contribute on the web](on-the-web.md) +* For **complex or multi-page updates**: [Contribute locally](locally.md) -This [tagging system](#applies-to) is mandatory for all of the public-facing documentation. +#### Branches in V3 -##### The `applies_to` tag [#applies-to] +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. -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) +* 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 -* 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) +* 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/releasing.md b/docs/contribute/releasing.md new file mode 100644 index 000000000..c91d232ad --- /dev/null +++ b/docs/contribute/releasing.md @@ -0,0 +1 @@ +# Releasing a new product version \ No newline at end of file diff --git a/docs/contribute/versioning/cumulative-docs.md b/docs/contribute/versioning/cumulative-docs.md new file mode 100644 index 000000000..35b0433f6 --- /dev/null +++ b/docs/contribute/versioning/cumulative-docs.md @@ -0,0 +1,307 @@ + + +Documentation is cumulative: As functionality changes, both the old and new functionality should be clear to the reader. Don’t delete or destructively edit content to remove context about previous versions. + + +Lifecycle statuses are additive: If a feature is beta in 9.1 and GA in 9.2, both statuses should be specified so users on any version can understand what applies to them. + + +# Write cumulative documentation {#write-cumulative-documentation} + +In our markdown-based documentation system, we write docs cumulatively regardless of the publication model 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. +* When a feature goes into a new state as compared to the established base version. + +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/)”. + +## Tagging products and deployment models + +**Page-level frontmatter mandatory** +First and foremost, each documentation page **must** specify which contexts it applies to in its [frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter). + +* 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, check [frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter). + /\!\\ When a key has no value, it is not rendered. + + +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 +--- +``` + +Note: 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 +--- +``` + +**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: + +* 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 in serverless): + +````md +## Configure a space-level landing page [space-landing-page] +```{applies_to} +stack: ga +serverless: unavailable +``` +```` + +* 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: + +````md +## Secure a deployment [secure-deployment-ech] +```{applies_to} +deployment: + ess: ga +``` + +[...] + +## Secure a deployment [secure-deployment-ece] +```{applies_to} +deployment: + ece: ga +``` + +[...] +```` + +* 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: + +```md +**Spaces** let you organize your content and users according to your needs. + +- 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. +- {applies_to}`stack: ga` {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. +``` + +**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 Elastic Cloud Hosted deployment just requires identifying “Elastic Cloud Hosted” 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: + +````yml +--- +applies_to: + stack: ga + serverless: ga +— + +# Spaces + +[...] + +## Configure a space-level landing page [space-landing-page] +```{applies_to} +stack: ga +serverless: unavailable +``` +```` +## 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 or Elastic Cloud, how do I tag it?** +Cumulative documentation is not meant to replace release notes. If a feature becomes available in Serverless 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](#choose-the-docs-deployment-model-for-a-repository). + +We do not do date-based tagging for unversioned products. + +**Feature lifecycle** + +* For unversioned products (typically Serverless and Elastic Cloud Hosted): + Unversioned products aren’t following 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`: + + +```yml +applies_to: + serverless: preview +``` + + + * When a change introduces a deprecation, use deprecated as value for the corresponding key within the `applies_to`: + +```yml +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: + +```yml +applies_to: + stack: deprecated 9.1, removed 9.4 + serverless: removed +``` + +* For versioned products: + + * When a change is released in GA, users need to know which version the feature became available in: + +```yml +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`: + +```yml +applies_to: + stack: beta 9.1 +``` + + + * When a change introduces a deprecation, use deprecated as value for the corresponding key within the `applies_to`: + +```yml +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: + +```yml +applies_to: + stack: deprecated 9.1, removed 9.4 +``` + + + +**Identify multiple states for the same content** +`applies_to` keys accept comma-separated values. 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 Elastic Cloud Hosted: + +```yml +applies_to: + deployment: + ece: deprecated 4.0, removed 4.8 + ess: removed +``` + +**How do these tags behave in the output?** +Applies\_to tags are rendered as badges in the documentation output. They reproduce the “key \+ lifecycle status \+ version” indicated in the sources. + +Specifically for versioned products, badges will show “Planned” (if the lifecycle is preview, beta, or ga), “Deprecation planned” (if the lifecycle is deprecated), or “Removal planned” (if the lifecycle is removed) when the `applies_to` key specifies a product version that has not been released to our customers yet. + +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. \ No newline at end of file diff --git a/docs/contribute/versioning/deployment-models.md b/docs/contribute/versioning/deployment-models.md new file mode 100644 index 000000000..9643cf486 --- /dev/null +++ b/docs/contribute/versioning/deployment-models.md @@ -0,0 +1,107 @@ +# Choose the docs deployment model for a repository {#choose-the-docs-deployment-model-for-a-repository} + +With 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. + +## 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](#write-cumulative-documentation), 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 and cloud. + + +## 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 disturbing to have the docs associated with a certain version live in a different branch than the code. + +Caveat: If you choose this publication model for your repository AND that repository includes serverless or cloud documentation, you will need to make sure that serverless and cloud related changes are also backported to the `current` branch in order to be published on time. + +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](#write-cumulative-documentation). + +## 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. + +Once it’s 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/625e75b35841be938a8df76a62deeee811ba52d4/src/tooling/docs-assembler/assembler.yml#L70): + * 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 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. +3. When these releases happen, create a PR against this file that defines the new `current` branch, to merge on release day. + +## Workflow 1 (default): Make docs updates when the repo is publishing docs from `main` + +### Where to make docs changes + +Initiate the changes by opening a PR against the `main` branch of the repo. + +### How to write those changes + +In our markdown-based documentation system, we [write docs cumulatively](#write-cumulative-documentation) regardless of the publication model selected. + +### Merging and backporting + +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.).

We have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. | You have the choice between merging the PR as soon as it is approved, or merging it only on release day. | +| 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), you are in the same situation as Case 1. | The PR should only be merged on or after the release date of the feature in Serverless. Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) 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 + +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: Make docs updates when the repo is publishing docs from a `version` branch + +### Where to make docs changes + +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 + +In our markdown-based documentation system, we [write docs cumulatively](#write-cumulative-documentation) regardless of the publication model selected. + +### Merging and backporting + +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.).

We have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as “Planned”. | 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. | +| 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), you are in the same situation as Case 1. | 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.

Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. | + +#### Example + +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 + +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/migration/versioning.md b/docs/migration/versioning.md index 46a40bfe6..486cbbbc5 100644 --- a/docs/migration/versioning.md +++ b/docs/migration/versioning.md @@ -4,113 +4,29 @@ 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](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 +`applies_to` tags are rendered as badges in the documentation output. They reproduce the "key + lifecycle status + version" indicated in the content sources. -## 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. -To support multiple deployment models for different repositories, we support the concept of a content source. +* `Planned` (if the lifecycle is preview, beta, or ga) +* `Deprecation planned` (if the lifecycle is deprecated) +* `Removal planned` (if the lifecycle is removed) -Next -: The source for the upcoming documentation. +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. -Current -: The source for the active documentation. +% todo: link +## Deployment models -Our publish environments are connected to a single content source. +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. -| 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 -::: - -#### 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: read -``` - -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 From 0129f7fa04f89a97b7bdaaf07f7564a3f5a5e73c Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 24 Jun 2025 17:47:12 -0400 Subject: [PATCH 02/12] more --- docs/_docset.yml | 7 ++--- .../{versioning => }/cumulative-docs.md | 31 +++++++++++-------- .../{versioning => }/deployment-models.md | 6 +++- docs/contribute/releasing.md | 4 ++- 4 files changed, 28 insertions(+), 20 deletions(-) rename docs/contribute/{versioning => }/cumulative-docs.md (92%) rename docs/contribute/{versioning => }/deployment-models.md (98%) diff --git a/docs/_docset.yml b/docs/_docset.yml index 4b245299d..5d163a606 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -31,11 +31,8 @@ toc: - file: on-the-web.md - file: move.md - file: redirects.md - - folder: versioning - children: - - file: index.md - - file: deployment-models.md - - file: cumulative-docs.md + - file: cumulative-docs.md + - file: deployment-models.md - file: releasing.md - folder: migration children: diff --git a/docs/contribute/versioning/cumulative-docs.md b/docs/contribute/cumulative-docs.md similarity index 92% rename from docs/contribute/versioning/cumulative-docs.md rename to docs/contribute/cumulative-docs.md index 35b0433f6..ed00c9e15 100644 --- a/docs/contribute/versioning/cumulative-docs.md +++ b/docs/contribute/cumulative-docs.md @@ -1,4 +1,4 @@ - +# Write cumulative documentation Documentation is cumulative: As functionality changes, both the old and new functionality should be clear to the reader. Don’t delete or destructively edit content to remove context about previous versions. @@ -6,7 +6,7 @@ Documentation is cumulative: As functionality changes, both the old and new func Lifecycle statuses are additive: If a feature is beta in 9.1 and GA in 9.2, both statuses should be specified so users on any version can understand what applies to them. -# Write cumulative documentation {#write-cumulative-documentation} +======= In our markdown-based documentation system, we write docs cumulatively regardless of the publication model selected. @@ -15,7 +15,9 @@ With our markdown-based docs, there is no longer a new documentation set publish 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. +:::{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. @@ -31,7 +33,7 @@ This tagging system is mandatory for all of the public-facing documentation. We ## Tagging products and deployment models -**Page-level frontmatter mandatory** +### Page-level frontmatter (mandatory) First and foremost, each documentation page **must** specify which contexts it applies to in its [frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter). * The `applies_to` attribute is used to display contextual badges on each page. @@ -110,7 +112,8 @@ products: --- ``` -**Section or inline contexts situational** +### 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: * 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 in serverless): @@ -153,7 +156,8 @@ deployment: - {applies_to}`stack: ga` {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. ``` -**When should I indicate that something is NOT applicable to a specific context?** +### 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 Elastic Cloud Hosted deployment just requires identifying “Elastic Cloud Hosted” as context. No need to overload the context with additional `serverless: unavailable` indicators. @@ -192,7 +196,7 @@ stack: ga serverless: unavailable ``` ```` -## Tagging version-related changes (mandatory) +## 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. @@ -207,9 +211,8 @@ However, in this scenario, it is important to consider carefully [when the chang We do not do date-based tagging for unversioned products. -**Feature lifecycle** +### For unversioned products (typically Serverless and Elastic Cloud Hosted) -* For unversioned products (typically Serverless and Elastic Cloud Hosted): Unversioned products aren’t following 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`: @@ -240,7 +243,7 @@ applies_to: serverless: removed ``` -* For versioned products: +### For versioned products * When a change is released in GA, users need to know which version the feature became available in: @@ -275,7 +278,7 @@ applies_to: -**Identify multiple states for the same content** +### Identify multiple states for the same content `applies_to` keys accept comma-separated values. For example: * A feature is added in 9.1 as tech preview and becomes GA in 9.4: @@ -295,7 +298,7 @@ applies_to: ess: removed ``` -**How do these tags behave in the output?** +## How do these tags behave in the output? Applies\_to tags are rendered as badges in the documentation output. They reproduce the “key \+ lifecycle status \+ version” indicated in the sources. Specifically for versioned products, badges will show “Planned” (if the lifecycle is preview, beta, or ga), “Deprecation planned” (if the lifecycle is deprecated), or “Removal planned” (if the lifecycle is removed) when the `applies_to` key specifies a product version that has not been released to our customers yet. @@ -304,4 +307,6 @@ This is computed at build time (there is a docs build every 30 minutes). The doc 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. \ No newline at end of file +:::{note} +Visuals and wording in the output documentation are subject to changes and optimizations. +::: \ No newline at end of file diff --git a/docs/contribute/versioning/deployment-models.md b/docs/contribute/deployment-models.md similarity index 98% rename from docs/contribute/versioning/deployment-models.md rename to docs/contribute/deployment-models.md index 9643cf486..2cf92e785 100644 --- a/docs/contribute/versioning/deployment-models.md +++ b/docs/contribute/deployment-models.md @@ -1,4 +1,8 @@ -# Choose the docs deployment model for a repository {#choose-the-docs-deployment-model-for-a-repository} +--- +navigation_title: Choose a deployment model +--- + +# Choose the docs deployment model for a repository With 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. diff --git a/docs/contribute/releasing.md b/docs/contribute/releasing.md index c91d232ad..8672b7b58 100644 --- a/docs/contribute/releasing.md +++ b/docs/contribute/releasing.md @@ -1 +1,3 @@ -# Releasing a new product version \ No newline at end of file +# Release a new product version + +todo \ No newline at end of file From d2aac67feef1dd73c6656803e182645bba4a01f5 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 25 Jun 2025 15:35:28 -0400 Subject: [PATCH 03/12] more fixes --- docs/_docset.yml | 3 +- docs/contribute/_snippets/docs-intro.md | 5 ++ docs/contribute/_snippets/guide-intro.md | 3 ++ docs/contribute/_snippets/tagged-warning.md | 7 +++ docs/contribute/_snippets/two-systems.md | 7 +++ docs/contribute/deployment-models.md | 13 +++-- docs/contribute/index.md | 21 +++----- docs/contribute/locally.md | 23 +++++---- docs/contribute/on-the-web.md | 57 ++++++++++++--------- docs/contribute/releasing.md | 3 -- 10 files changed, 84 insertions(+), 58 deletions(-) create mode 100644 docs/contribute/_snippets/docs-intro.md create mode 100644 docs/contribute/_snippets/guide-intro.md create mode 100644 docs/contribute/_snippets/tagged-warning.md create mode 100644 docs/contribute/_snippets/two-systems.md delete mode 100644 docs/contribute/releasing.md diff --git a/docs/_docset.yml b/docs/_docset.yml index 5d163a606..10dcfe720 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -13,6 +13,8 @@ subs: serverless-short: Serverless ece: "Elastic Cloud Enterprise" eck: "Elastic Cloud on Kubernetes" + ech: "Elastic Cloud Hosted" + serverless-full: "Elastic Cloud Serverless" features: primary-nav: false @@ -33,7 +35,6 @@ toc: - file: redirects.md - file: cumulative-docs.md - file: deployment-models.md - - file: releasing.md - folder: migration children: - file: index.md diff --git a/docs/contribute/_snippets/docs-intro.md b/docs/contribute/_snippets/docs-intro.md new file mode 100644 index 000000000..be41255fc --- /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.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](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/tagged-warning.md b/docs/contribute/_snippets/tagged-warning.md new file mode 100644 index 000000000..d213569dc --- /dev/null +++ b/docs/contribute/_snippets/tagged-warning.md @@ -0,0 +1,7 @@ +:::{caution} +Some repositories use a [tagged deployment model](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-make-docs-updates-when-the-repo-is-publishing-docs-from-a-version-branch). + +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..e440c9ced --- /dev/null +++ b/docs/contribute/_snippets/two-systems.md @@ -0,0 +1,7 @@ +The way that you contribute to the docs depends on the product version. + +For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs), refer to [Find docs for your product version](/get-started/versioning-availability.md#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/deployment-models.md b/docs/contribute/deployment-models.md index 2cf92e785..ab9bf735e 100644 --- a/docs/contribute/deployment-models.md +++ b/docs/contribute/deployment-models.md @@ -34,9 +34,12 @@ Once it’s been established that a repository should publish from a version bra * 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 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. -3. When these releases happen, create a PR against this file that defines the new `current` branch, to merge on release day. + * 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. +4. When these releases happen, create a PR against this file that defines the new `current` branch, to merge on release day. + +For more information, refer to [](/configure/deployment-models.md). ## Workflow 1 (default): Make docs updates when the repo is publishing docs from `main` @@ -56,7 +59,7 @@ When a repo publishes docs from its `main` branch, any merged changes are publis | --- | --- | --- | | 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.).

We have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. | You have the choice between merging the PR as soon as it is approved, or merging it only on release day. | -| 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), you are in the same situation as Case 1. | The PR should only be merged on or after the release date of the feature in Serverless. Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) 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), you are in the same situation as Case 1. | The PR should only be merged on or after the release date of the feature in Serverless. Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) 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. @@ -88,7 +91,7 @@ The changes must then be backported to their relevant version branches, and no f | --- | --- | --- | | 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.).

We have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as “Planned”. | 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. | -| 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), you are in the same situation as Case 1. | 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.

Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) 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), you are in the same situation as Case 1. | 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.

Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. | #### Example diff --git a/docs/contribute/index.md b/docs/contribute/index.md index b02bbe231..e379cf533 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -12,32 +12,23 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi 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}}. -The way that you contribute to the docs depends on the product version. - -For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs), refer to [Find docs for your product version](/get-started/versioning-availability.md#find-docs-for-your-product-version). Versions previous 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). +:::{include} _snippets/two-systems.md ::: ### Contribute to elastic.co/guide -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. +:::{include} _snippets/guide-intro.md +::: * 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) ### Contribute elastic.co/docs -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.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](cumulative-docs.md). +:::{include} _snippets/docs-intro.md +::: -* For **simple bug fixes and enhancements**: [contribute on the web](on-the-web.md) +* For **simple bug fixes and enhancements**: [Contribute on the web](on-the-web.md) * For **complex or multi-page updates**: [Contribute locally](locally.md) #### Branches in V3 diff --git a/docs/contribute/locally.md b/docs/contribute/locally.md index bcbe30299..27affaf17 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} 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..7c5b99dfa 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} 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/contribute/releasing.md b/docs/contribute/releasing.md deleted file mode 100644 index 8672b7b58..000000000 --- a/docs/contribute/releasing.md +++ /dev/null @@ -1,3 +0,0 @@ -# Release a new product version - -todo \ No newline at end of file From b56af45258dabfc489a16ff1abf5527316d8f019 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 25 Jun 2025 16:44:33 -0400 Subject: [PATCH 04/12] squish together --- docs/_docset.yml | 1 + docs/configure/deployment-models.md | 2 +- docs/contribute/_snippets/tag-processing.md | 17 + docs/contribute/_snippets/two-systems.md | 2 +- docs/contribute/cumulative-docs.md | 316 +++++++----------- docs/contribute/deployment-models.md | 67 ++-- docs/contribute/index.md | 6 +- docs/migration/versioning.md | 13 +- .../_snippets/multiple-lifecycle-states.md | 21 ++ .../syntax/_snippets/unversioned-lifecycle.md | 33 ++ docs/syntax/_snippets/versioned-lifecycle.md | 36 ++ docs/syntax/applies.md | 79 +---- docs/versions/content-patterns.md | 4 + docs/versions/index.md | 4 + 14 files changed, 286 insertions(+), 315 deletions(-) create mode 100644 docs/contribute/_snippets/tag-processing.md create mode 100644 docs/syntax/_snippets/multiple-lifecycle-states.md create mode 100644 docs/syntax/_snippets/unversioned-lifecycle.md create mode 100644 docs/syntax/_snippets/versioned-lifecycle.md diff --git a/docs/_docset.yml b/docs/_docset.yml index 10dcfe720..bf9e276c3 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -15,6 +15,7 @@ subs: eck: "Elastic Cloud on Kubernetes" ech: "Elastic Cloud Hosted" serverless-full: "Elastic Cloud Serverless" + ecloud: "Elastic Cloud" features: primary-nav: false diff --git a/docs/configure/deployment-models.md b/docs/configure/deployment-models.md index 3bba8e11c..fcd343ee3 100644 --- a/docs/configure/deployment-models.md +++ b/docs/configure/deployment-models.md @@ -1,4 +1,4 @@ -# Content Sources +# Content sources To support multiple deployment models for different repositories, we support the concept of a content source. diff --git a/docs/contribute/_snippets/tag-processing.md b/docs/contribute/_snippets/tag-processing.md new file mode 100644 index 000000000..7e6a6bb77 --- /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 \ No newline at end of file diff --git a/docs/contribute/_snippets/two-systems.md b/docs/contribute/_snippets/two-systems.md index e440c9ced..688394586 100644 --- a/docs/contribute/_snippets/two-systems.md +++ b/docs/contribute/_snippets/two-systems.md @@ -1,4 +1,4 @@ -The way that you contribute to the docs depends on the product version. +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](/get-started/versioning-availability.md#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). diff --git a/docs/contribute/cumulative-docs.md b/docs/contribute/cumulative-docs.md index ed00c9e15..e73291ba2 100644 --- a/docs/contribute/cumulative-docs.md +++ b/docs/contribute/cumulative-docs.md @@ -1,35 +1,29 @@ # Write cumulative documentation -Documentation is cumulative: As functionality changes, both the old and new functionality should be clear to the reader. Don’t delete or destructively edit content to remove context about previous versions. +In our markdown-based documentation system, we write docs cumulatively regardless of the [deployment model](deployment-models.md) selected. +**What does this mean?** -Lifecycle statuses are additive: If a feature is beta in 9.1 and GA in 9.2, both statuses should be specified so users on any version can understand what applies to them. - - -======= - -In our markdown-based documentation system, we write docs cumulatively regardless of the publication model 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. +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?** +**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. -* When a feature goes into a new state as compared to the established base version. +* [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/)”. +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 @@ -39,58 +33,56 @@ First and foremost, each documentation page **must** specify which contexts it a * 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, check [frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter). - /\!\\ When a key has no value, it is not rendered. - + For the full list of supported keys and values, refer to [frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter). 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 ---- -``` + ```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 ---- - -``` + ```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 ---- -``` - -Note: 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: + 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 --- @@ -111,202 +103,126 @@ products: -id: cloud-kubernetes --- ``` +% I don't know what this example is supposed to show ### 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: -* 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 in serverless): +* 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 in {{serverless-short}}): -````md -## Configure a space-level landing page [space-landing-page] -```{applies_to} -stack: ga -serverless: unavailable -``` -```` + ````md + ## Configure a space-level landing page [space-landing-page] + ```{applies_to} + stack: ga + serverless: unavailable + ``` + ```` -* 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: +* 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 -## Secure a deployment [secure-deployment-ech] -```{applies_to} -deployment: - ess: ga -``` + ````md + ## Cloud organization level security [cloud-organization-level] + ```{applies_to} + deployment: + ess: ga + serverless: ga + ``` -[...] + [...] -## Secure a deployment [secure-deployment-ece] -```{applies_to} -deployment: - ece: ga -``` + ## Orchestrator level security [orchestrator-level] + ```{applies_to} + deployment: + ece: ga + ``` -[...] -```` + [...] + ```` * 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: -```md -**Spaces** let you organize your content and users according to your needs. + ```md + **Spaces** let you organize your content and users according to your needs. -- 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. -- {applies_to}`stack: ga` {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. -``` + - 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. + - {applies_to}`stack: ga` {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. + ``` ### 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 Elastic Cloud Hosted deployment just requires identifying “Elastic Cloud Hosted” as context. No need to overload the context with additional `serverless: unavailable` indicators. +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 ---- -``` + ```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: -````yml ---- -applies_to: - stack: ga - serverless: ga -— + ````yml + --- + applies_to: + stack: ga + serverless: ga + — -# Spaces + # 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 -## Configure a space-level landing page [space-landing-page] -```{applies_to} -stack: ga -serverless: unavailable -``` -```` ## 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. +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 or Elastic Cloud, how do I tag it?** -Cumulative documentation is not meant to replace release notes. If a feature becomes available in Serverless and doesn’t have a particular lifecycle state to call out (preview, beta, deprecated…), it does not need specific tagging. +**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](#choose-the-docs-deployment-model-for-a-repository). We do not do date-based tagging for unversioned products. -### For unversioned products (typically Serverless and Elastic Cloud Hosted) - - Unversioned products aren’t following 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`: - - -```yml -applies_to: - serverless: preview -``` - - - * When a change introduces a deprecation, use deprecated as value for the corresponding key within the `applies_to`: - -```yml -applies_to: - deployment: - ess: deprecated -``` - - +### For unversioned products (typically {{serverless-short}} and {{ech}}) - * 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: - -```yml -applies_to: - stack: deprecated 9.1, removed 9.4 - serverless: removed -``` +:::{include} /syntax/_snippets/unversioned-lifecycle.md +::: ### For versioned products - * When a change is released in GA, users need to know which version the feature became available in: - -```yml -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`: - -```yml -applies_to: - stack: beta 9.1 -``` - - - * When a change introduces a deprecation, use deprecated as value for the corresponding key within the `applies_to`: - -```yml -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: - -```yml -applies_to: - stack: deprecated 9.1, removed 9.4 -``` - - +:::{include} /syntax/_snippets/versioned-lifecycle.md +::: ### Identify multiple states for the same content -`applies_to` keys accept comma-separated values. 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 Elastic Cloud Hosted: - -```yml -applies_to: - deployment: - ece: deprecated 4.0, removed 4.8 - ess: removed -``` +:::{include} /syntax/_snippets/multiple-lifecycle-states.md +::: -## How do these tags behave in the output? -Applies\_to tags are rendered as badges in the documentation output. They reproduce the “key \+ lifecycle status \+ version” indicated in the sources. - -Specifically for versioned products, badges will show “Planned” (if the lifecycle is preview, beta, or ga), “Deprecation planned” (if the lifecycle is deprecated), or “Removal planned” (if the lifecycle is removed) when the `applies_to` key specifies a product version that has not been released to our customers yet. - -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. +## How do these tags behave in the output? -:::{note} -Visuals and wording in the output documentation are subject to changes and optimizations. +:::{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 index ab9bf735e..db75748db 100644 --- a/docs/contribute/deployment-models.md +++ b/docs/contribute/deployment-models.md @@ -4,62 +4,69 @@ navigation_title: Choose a deployment model # Choose the docs deployment model for a repository -With 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. +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](#write-cumulative-documentation), 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 and cloud. +* 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 disturbing to have the docs associated with a certain version live in a different branch than the code. +* `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. -Caveat: If you choose this publication model for your repository AND that repository includes serverless or cloud documentation, you will need to make sure that serverless and cloud 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](#write-cumulative-documentation). +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. -Once it’s been established that a repository should publish from a version branch rather than `main`: +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/625e75b35841be938a8df76a62deeee811ba52d4/src/tooling/docs-assembler/assembler.yml#L70): +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. -4. When these releases happen, create a PR against this file that defines the new `current` branch, to merge on release day. +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): Make docs updates when the repo is publishing docs from `main` +## Workflow 1 (default): Continuous deployment -### Where to make docs changes +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 +### How to write those changes [write-changes-cd] -In our markdown-based documentation system, we [write docs cumulatively](#write-cumulative-documentation) regardless of the publication model selected. +In our markdown-based documentation system, we [write docs cumulatively](cumulative-docs.md) regardless of the publication model selected. -### Merging and backporting +### 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.).

We have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. | You have the choice between merging the PR as soon as it is approved, or merging it only on release day. | -| 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), you are in the same situation as Case 1. | The PR should only be merged on or after the release date of the feature in Serverless. Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as `Planned`. | +| 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. @@ -67,21 +74,23 @@ When a repo is publishing docs from its `main` branch, no backporting is needed. 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 [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: Make docs updates when the repo is publishing docs from a `version` branch +## 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 +### 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 +### How to write those changes [write-changes-td] -In our markdown-based documentation system, we [write docs cumulatively](#write-cumulative-documentation) regardless of the publication model selected. +In our markdown-based documentation system, we [write docs cumulatively](cumulative-docs.md) regardless of the publication model selected. -### Merging and backporting +### 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. @@ -90,10 +99,10 @@ 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.).

We have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) that will show any changes published before its associated code or feature is available as “Planned”. | 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. | -| 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), you are in the same situation as Case 1. | 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.

Note that for versioned products, we have an automatic mechanism in place as part of the [cumulative docs strategy](#write-cumulative-documentation) 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](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 [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: @@ -109,6 +118,6 @@ For example, in a situation where 9.0, 9.1, and 9.2 are already released, and th 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 [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 e379cf533..f41eedc0b 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -39,12 +39,12 @@ In Docs V3, a single branch is published per repository. This branch is set to ` ## 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 **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 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/migration/versioning.md b/docs/migration/versioning.md index 486cbbbc5..e3d621c95 100644 --- a/docs/migration/versioning.md +++ b/docs/migration/versioning.md @@ -12,17 +12,8 @@ In this new system, documentation is written **cumulatively**. This means that a ## Tag processing -`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. - -% todo: link +:::{include} /contribute/_snippets/tag-processing.md +::: ## Deployment models diff --git a/docs/syntax/_snippets/multiple-lifecycle-states.md b/docs/syntax/_snippets/multiple-lifecycle-states.md new file mode 100644 index 000000000..2d739111c --- /dev/null +++ b/docs/syntax/_snippets/multiple-lifecycle-states.md @@ -0,0 +1,21 @@ +FIX ME!!! + + +`applies_to` keys accept comma-separated values. 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/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 2c11acafc..4fcab327d 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,6 +1,6 @@ # 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. @@ -16,7 +16,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. @@ -38,18 +38,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,75 +86,14 @@ 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 - --- - ``` +:::{include} _snippets/unversioned-lifecycle.md +::: #### 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 - --- - ``` - -* 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 - --- - ``` +:::{include} _snippets/versioned-lifecycle.md +::: #### Identify multiple states for the same content diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index e914bf3d9..388edebfb 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. From 490dea077d1106470f6193c8a0e0eefc826f86b2 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 26 Jun 2025 15:11:37 -0400 Subject: [PATCH 05/12] unify examples --- docs/contribute/cumulative-docs.md | 118 ++-------------- .../_snippets/line-level-applies-example.md | 7 + .../_snippets/multiple-lifecycle-states.md | 5 +- .../_snippets/page-level-applies-examples.md | 73 ++++++++++ .../section-level-applies-examples.md | 41 ++++++ docs/syntax/applies.md | 126 ++---------------- 6 files changed, 145 insertions(+), 225 deletions(-) create mode 100644 docs/syntax/_snippets/line-level-applies-example.md create mode 100644 docs/syntax/_snippets/page-level-applies-examples.md create mode 100644 docs/syntax/_snippets/section-level-applies-examples.md diff --git a/docs/contribute/cumulative-docs.md b/docs/contribute/cumulative-docs.md index e73291ba2..e13267131 100644 --- a/docs/contribute/cumulative-docs.md +++ b/docs/contribute/cumulative-docs.md @@ -28,127 +28,29 @@ This tagging system is mandatory for all of the public-facing documentation. We ## Tagging products and deployment models ### Page-level frontmatter (mandatory) -First and foremost, each documentation page **must** specify which contexts it applies to in its [frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter). + +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). -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 +:::{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: -* 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 in {{serverless-short}}): - - ````md - ## Configure a space-level landing page [space-landing-page] - ```{applies_to} - stack: ga - serverless: unavailable - ``` - ```` - -* 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 - ``` - - [...] - ```` +:::{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: - ```md - **Spaces** let you organize your content and users according to your needs. - - - 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. - - {applies_to}`stack: ga` {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. - ``` + :::{include} _snippets/line-level-applies-example.md + ::: ### When should I indicate that something is NOT applicable to a specific context? @@ -173,12 +75,12 @@ 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: - ````yml + ````md --- applies_to: stack: ga serverless: ga - — + —-- # Spaces 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 index 2d739111c..bb0bedf40 100644 --- a/docs/syntax/_snippets/multiple-lifecycle-states.md +++ b/docs/syntax/_snippets/multiple-lifecycle-states.md @@ -1,7 +1,4 @@ -FIX ME!!! - - -`applies_to` keys accept comma-separated values. For example: +`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: 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..816a5f581 --- /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..163a8d389 --- /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): + + ````markdown + --- + 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/applies.md b/docs/syntax/applies.md index 4fcab327d..6a3113f3b 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -97,66 +97,17 @@ applies_to: #### 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 @@ -202,54 +153,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 @@ -263,17 +168,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): +* 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. + :::{include} _snippets/line-level-applies-example.md + ::: - - Each space has its own saved objects. - - {applies_to}`stack: ga` {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. - ```` - -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}`` @@ -301,5 +202,4 @@ applies_to: observability: product: --- -``` -This allows you to annotate various facets as defined in [](../migration/versioning.md) \ No newline at end of file +``` \ No newline at end of file From 08cadd12d57b2803f9df008bc4cbe2311c56b5a6 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 26 Jun 2025 16:09:10 -0400 Subject: [PATCH 06/12] more --- docs/contribute/_snippets/tag-processing.md | 4 ++-- docs/contribute/cumulative-docs.md | 4 ++++ .../_snippets/section-level-applies-examples.md | 2 +- docs/syntax/applies.md | 12 ++++++++++++ 4 files changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/contribute/_snippets/tag-processing.md b/docs/contribute/_snippets/tag-processing.md index 7e6a6bb77..3c1003d41 100644 --- a/docs/contribute/_snippets/tag-processing.md +++ b/docs/contribute/_snippets/tag-processing.md @@ -1,6 +1,6 @@ `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. +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) @@ -14,4 +14,4 @@ When multiple lifecycle statuses and versions are specified in the sources, seve Visuals and wording in the output documentation are subject to changes and optimizations. ::: -% todo: link \ No newline at end of file +% todo: link to central config \ No newline at end of file diff --git a/docs/contribute/cumulative-docs.md b/docs/contribute/cumulative-docs.md index e13267131..52ef04157 100644 --- a/docs/contribute/cumulative-docs.md +++ b/docs/contribute/cumulative-docs.md @@ -1,5 +1,9 @@ # 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?** diff --git a/docs/syntax/_snippets/section-level-applies-examples.md b/docs/syntax/_snippets/section-level-applies-examples.md index 163a8d389..00b5f14c1 100644 --- a/docs/syntax/_snippets/section-level-applies-examples.md +++ b/docs/syntax/_snippets/section-level-applies-examples.md @@ -1,6 +1,6 @@ * 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): - ````markdown + ````md --- applies_to: stack: ga diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 6a3113f3b..aefe3ad72 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,5 +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. To support this, source files use a tagging system to indicate: @@ -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: @@ -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). From 50b970ad1a28b98a9530df5f34f41a0d7747d0ec Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 26 Jun 2025 16:11:01 -0400 Subject: [PATCH 07/12] fix --- .../_snippets/page-level-applies-examples.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/syntax/_snippets/page-level-applies-examples.md b/docs/syntax/_snippets/page-level-applies-examples.md index 816a5f581..b15e6c9c4 100644 --- a/docs/syntax/_snippets/page-level-applies-examples.md +++ b/docs/syntax/_snippets/page-level-applies-examples.md @@ -25,10 +25,10 @@ There are 3 typical scenarios to start from: ece: ga eck: ga products: - -id: cloud-serverless - -id: cloud-hosted - -id: cloud-enterprise - -id: cloud-kubernetes + - id: cloud-serverless + - id: cloud-hosted + - id: cloud-enterprise + - id: cloud-kubernetes --- ``` @@ -40,7 +40,7 @@ There are 3 typical scenarios to start from: applies_to: product: ga products: - -id: edot-collector + - id: edot-collector --- ``` % changing soon @@ -57,13 +57,13 @@ applies_to: ece: ga eck: ga products: - -id: kibana - -id: elasticsearch - -id: elastic-stack - -id: cloud-serverless - -id: cloud-hosted - -id: cloud-enterprise - -id: cloud-kubernetes + - 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 From c66960fcc97361ca37948b91681480e591d53b57 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 26 Jun 2025 16:13:55 -0400 Subject: [PATCH 08/12] fix --- docs/configure/deployment-models.md | 4 ++-- docs/contribute/cumulative-docs.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/configure/deployment-models.md b/docs/configure/deployment-models.md index fcd343ee3..4f950f132 100644 --- a/docs/configure/deployment-models.md +++ b/docs/configure/deployment-models.md @@ -33,7 +33,7 @@ Tagged deployment ### 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 +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`. @@ -69,7 +69,7 @@ references: ``` :::{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. +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 ::: diff --git a/docs/contribute/cumulative-docs.md b/docs/contribute/cumulative-docs.md index 52ef04157..cd439a4c2 100644 --- a/docs/contribute/cumulative-docs.md +++ b/docs/contribute/cumulative-docs.md @@ -53,7 +53,7 @@ When the context differs from what was specified at the page level in a specific * 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} _snippets/line-level-applies-example.md + :::{include} /syntax/_snippets/line-level-applies-example.md ::: ### When should I indicate that something is NOT applicable to a specific context? @@ -109,7 +109,7 @@ 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](#choose-the-docs-deployment-model-for-a-repository). +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. From 1c72af09c9c09cd870fc4454374fcdcd5d95e8be Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 26 Jun 2025 16:30:09 -0400 Subject: [PATCH 09/12] edits --- docs/configure/deployment-models.md | 2 +- docs/contribute/_snippets/docs-intro.md | 4 ++-- docs/contribute/_snippets/two-systems.md | 2 +- docs/contribute/add-repo.md | 4 ++++ 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/configure/deployment-models.md b/docs/configure/deployment-models.md index 4f950f132..cc48e33a3 100644 --- a/docs/configure/deployment-models.md +++ b/docs/configure/deployment-models.md @@ -19,7 +19,7 @@ Our publish environments are connected to a single content source. This allows you as an owner of a repository to choose two different deployment models. -## Deployment models. +## Deployment models The new documentation system supports 2 deployment models. diff --git a/docs/contribute/_snippets/docs-intro.md b/docs/contribute/_snippets/docs-intro.md index be41255fc..da6162298 100644 --- a/docs/contribute/_snippets/docs-intro.md +++ b/docs/contribute/_snippets/docs-intro.md @@ -1,5 +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.md) to learn more. +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](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.md). \ No newline at end of file diff --git a/docs/contribute/_snippets/two-systems.md b/docs/contribute/_snippets/two-systems.md index 688394586..3b70902ab 100644 --- a/docs/contribute/_snippets/two-systems.md +++ b/docs/contribute/_snippets/two-systems.md @@ -1,6 +1,6 @@ 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](/get-started/versioning-availability.md#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). +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**: From 0df1b3c2345e652159cd8eb6e7f99b7b2d88e122 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 26 Jun 2025 16:42:17 -0400 Subject: [PATCH 10/12] fix --- docs/contribute/_snippets/tagged-warning.md | 2 +- docs/contribute/locally.md | 2 +- docs/contribute/on-the-web.md | 2 +- docs/migration/versioning.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contribute/_snippets/tagged-warning.md b/docs/contribute/_snippets/tagged-warning.md index d213569dc..901efce30 100644 --- a/docs/contribute/_snippets/tagged-warning.md +++ b/docs/contribute/_snippets/tagged-warning.md @@ -1,4 +1,4 @@ -:::{caution} +:::{warning} Some repositories use a [tagged deployment model](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-make-docs-updates-when-the-repo-is-publishing-docs-from-a-version-branch). diff --git a/docs/contribute/locally.md b/docs/contribute/locally.md index 27affaf17..d682ce772 100644 --- a/docs/contribute/locally.md +++ b/docs/contribute/locally.md @@ -155,7 +155,7 @@ We write docs in Markdown. Refer to our [syntax](../syntax/index.md) guide for t 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} tagged-warning.md +:::{include} _snippets/tagged-warning.md ::: ## Step 5: Push your changes [#step-five] diff --git a/docs/contribute/on-the-web.md b/docs/contribute/on-the-web.md index 7c5b99dfa..deb3f543b 100644 --- a/docs/contribute/on-the-web.md +++ b/docs/contribute/on-the-web.md @@ -38,7 +38,7 @@ For content hosted on elastic.co/docs, most conceptual and narrative content is 4. Make the necessary updates. 5. Commit your changes and create a pull request. -:::{include} tagged-warning.md +:::{include} _snippets/tagged-warning.md ::: ## What if I need to update docs in both systems? diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md index e3d621c95..a1d9201c6 100644 --- a/docs/migration/versioning.md +++ b/docs/migration/versioning.md @@ -8,7 +8,7 @@ To ensure a seamless experience for users and contributors, the new versioning a * **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](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.md). ## Tag processing From d9af7382caf587645a9d4ef3e219b77cc25ee372 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 26 Jun 2025 16:45:31 -0400 Subject: [PATCH 11/12] more bad links --- docs/contribute/_snippets/tagged-warning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contribute/_snippets/tagged-warning.md b/docs/contribute/_snippets/tagged-warning.md index 901efce30..c52f3b3ab 100644 --- a/docs/contribute/_snippets/tagged-warning.md +++ b/docs/contribute/_snippets/tagged-warning.md @@ -1,7 +1,7 @@ :::{warning} -Some repositories use a [tagged deployment model](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. +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-make-docs-updates-when-the-repo-is-publishing-docs-from-a-version-branch). +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). ::: From 4764c5b2fe1209240f18dcd2a1802ccd377a6e58 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Thu, 26 Jun 2025 16:57:06 -0400 Subject: [PATCH 12/12] Update docs/configure/deployment-models.md Co-authored-by: Jan Calanog --- docs/configure/deployment-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configure/deployment-models.md b/docs/configure/deployment-models.md index cc48e33a3..c38e70c5a 100644 --- a/docs/configure/deployment-models.md +++ b/docs/configure/deployment-models.md @@ -98,7 +98,7 @@ jobs: deployments: write id-token: write contents: read - pull-requests: read + pull-requests: write ``` 1. Ensure version branches are built and publish their links ahead of time. \ No newline at end of file