diff --git a/contribute-docs/_snippets-contribute/guide-intro.md b/contribute-docs/_snippets-contribute/guide-intro.md deleted file mode 100644 index 2c1177ab64..0000000000 --- a/contribute-docs/_snippets-contribute/guide-intro.md +++ /dev/null @@ -1,3 +0,0 @@ -To contribute to `elastic.co/guide` (Asciidoc), you must work with our [Asciidoc 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/contribute-docs/_snippets-contribute/tag-processing.md b/contribute-docs/_snippets-contribute/tag-processing.md deleted file mode 100644 index 8b9fd2e67a..0000000000 --- a/contribute-docs/_snippets-contribute/tag-processing.md +++ /dev/null @@ -1,26 +0,0 @@ -`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. - -The following table shows how badges for versioned products are displayed based on the release status for each lifecycle value. Hover over the example badges for the tooltip text. - -| Lifecycle | Release status | Badge text examples | -|-------------|----------------|---------------------------------------| -| preview | prerelease | {applies_to}`stack: preview 99.99` | -| | post-release | {applies_to}`stack: preview 9.1` | -| beta | prerelease | {applies_to}`stack: beta 99.99` | -| | post-release | {applies_to}`stack: beta 9.1` | -| ga | prerelease | {applies_to}`stack: ga 99.99` | -| | post-release | {applies_to}`stack: ga 9.1` | -| deprecated | prerelease | {applies_to}`stack: deprecated 99.99` | -| | post-release | {applies_to}`stack: deprecated 9.1` | -| removed | prerelease | {applies_to}`stack: removed 99.99` | -| | post-release | {applies_to}`stack: removed 9.1` | - -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 in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml). - -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. -::: diff --git a/contribute-docs/_snippets-contribute/two-systems.md b/contribute-docs/_snippets-contribute/two-systems.md deleted file mode 100644 index ae48c4e1b5..0000000000 --- a/contribute-docs/_snippets-contribute/two-systems.md +++ /dev/null @@ -1,7 +0,0 @@ -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) (Markdown), 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 [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/contribute-docs/_snippets/applies_to-version.md b/contribute-docs/_snippets/applies_to-version.md index 1bfb2c12eb..d268fb2950 100644 --- a/contribute-docs/_snippets/applies_to-version.md +++ b/contribute-docs/_snippets/applies_to-version.md @@ -1,9 +1,18 @@ `applies_to` accepts the following version formats: -* `Major.Minor` -* `Major.Minor.Patch` +| Format | Syntax | Examples | Badge Display | Description | +|:-------|:-------|:---------|:--------------|:------------| +| **Greater than or equal to** (default) | `x.x+`
`x.x`
`x.x.x+`
`x.x.x` | `ga 9.1`
`ga 9.1+` | `9.1+` | Applies from this version onwards | +| **Range** (inclusive) | `x.x-y.y`
`x.x.x-y.y.y` | `preview 9.0-9.2` | `9.0-9.2`
`9.0+`* | Applies within the specified range | +| **Exact version** | `=x.x`
`=x.x.x` | `beta =9.1` | `9.1` | Applies only to this specific version | -Regardless of the version format used in the source file, the version number is always rendered in the `Major.Minor.Patch` format. +\* Range display depends on release status of the second version. + +**Important notes:** + +- Versions are always displayed as **Major.Minor** (for example, `9.1`) in badges, regardless of whether you specify patch versions in the source. +- Each version statement corresponds to the **latest patch** of the specified minor version (for example, `9.1` represents 9.1.6 if 9.1.6 is the latest patch available for the 9.1 series). +- When critical patch-level differences exist, use plain text descriptions alongside the badge rather than specifying patch versions. :::{note} **Automatic Version Sorting**: When you specify multiple versions for the same product, the build system automatically sorts them in descending order (highest version first) regardless of the order you write them in the source file. For example, `stack: preview =9.0, ga 9.1-9.7, deprecated =9.8, removed 9.9+` will be displayed as `stack: removed 9.9+, deprecated =9.8, ga 9.1-9.7, preview =9.0`. Items without versions (like `ga` without a version or `all`) are sorted last. diff --git a/contribute-docs/_snippets/stack-serverless-lifecycle-example.md b/contribute-docs/_snippets/stack-serverless-lifecycle-example.md index b0cfc667bb..1a63fa508d 100644 --- a/contribute-docs/_snippets/stack-serverless-lifecycle-example.md +++ b/contribute-docs/_snippets/stack-serverless-lifecycle-example.md @@ -4,7 +4,7 @@ If a change is released in Serverless and will be released in a future version o --- applies_to: serverless: ga - stack: ga 9.2 + stack: ga 9.2+ --- ``` @@ -18,4 +18,4 @@ Because these changes need to be published as soon as the feature is released in * After the {{stack}} version is released, the same badges will render with the version number without any changes to the badge value in the source. {applies_to}`serverless: ga` - {applies_to}`stack: ga 9.0` \ No newline at end of file + {applies_to}`stack: ga 9.2+` \ No newline at end of file diff --git a/contribute-docs/_snippets/tag-processing.md b/contribute-docs/_snippets/tag-processing.md index 8b9fd2e67a..6a225afd0f 100644 --- a/contribute-docs/_snippets/tag-processing.md +++ b/contribute-docs/_snippets/tag-processing.md @@ -17,9 +17,7 @@ The following table shows how badges for versioned products are displayed based | removed | prerelease | {applies_to}`stack: removed 99.99` | | | post-release | {applies_to}`stack: removed 9.1` | -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 in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml). - -When multiple lifecycle statuses and versions are specified in the sources, several badges are shown. +This is computed at build time. The documentation team tracks and maintains released versions for these products centrally in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml). :::{note} Visuals and wording in the output documentation are subject to changes and optimizations. diff --git a/contribute-docs/_snippets-contribute/tagged-warning.md b/contribute-docs/_snippets/tagged-warning.md similarity index 100% rename from contribute-docs/_snippets-contribute/tagged-warning.md rename to contribute-docs/_snippets/tagged-warning.md diff --git a/contribute-docs/how-to/cumulative-docs/badge-placement.md b/contribute-docs/how-to/cumulative-docs/badge-placement.md index 19cd37e9f6..339a1f79d3 100644 --- a/contribute-docs/how-to/cumulative-docs/badge-placement.md +++ b/contribute-docs/how-to/cumulative-docs/badge-placement.md @@ -3,7 +3,7 @@ :::{note} This content is still in development. If you have questions about how to write cumulative documentation while contributing, -reach out to **@elastic/docs** in the related GitHub issue or PR. +reach out to **@elastic/docs** in the related GitHub issue or PR. ::: As you continue contributing to documentation and more versions are released, @@ -19,13 +19,12 @@ version and deployment type differences in your docs: * **Headings**: Provide signals about a section’s scope so a user can choose to read or skip it as needed. * **Lists**: Identify features in a list of features that are exclusive to a specific context, or that were introduced in a specific version or comparing differing requirements, limits, and other simple, mirrored facts. * **Definition lists**: Identify settings or options that are exclusive to a specific context, or that were introduced in a specific version. -* **Tabs**: Provide two sets of procedures when one or more steps in a process differs between contexts or versions. +* **Tabs**: Provide two sets of procedures when one or more steps in a process differs between contexts. For differences per version or deployment type, you should use [`applies-switch`](https://elastic.github.io/docs-builder/syntax/applies-switch/) instead of a generic [`tab-set`](https://elastic.github.io/docs-builder/syntax/tabs/). * **Admonitions**: Draw attention to happy differences and basic clarifications. * **Sibling pages**: When the information is too complex to be addressed with only the other content patterns. ## General placement principles -% Source: Brandon's PR review comment At a high level, you should follow these badge placement principles: * Place badges where they're most visible but least disruptive to reading flow. diff --git a/contribute-docs/how-to/cumulative-docs/example-scenarios.md b/contribute-docs/how-to/cumulative-docs/example-scenarios.md index caf42b5f1d..86300dc5b7 100644 --- a/contribute-docs/how-to/cumulative-docs/example-scenarios.md +++ b/contribute-docs/how-to/cumulative-docs/example-scenarios.md @@ -7,7 +7,7 @@ navigation_title: Example scenarios :::{note} This content is still in development. If you have questions about how to write cumulative documentation while contributing, -reach out to **@elastic/docs** in the related GitHub issue or PR. +reach out to **@elastic/docs** in the related GitHub issue or PR. ::: Browse common scenarios you might run into as a docs contributor that require different approaches to labeling cumulative docs. @@ -226,7 +226,7 @@ applies_to: #### Tables -**Density** {applies_to}`stack: ga 9.1` {applies_to}`serverless: ga` +**Density** {applies_to}`stack: ga 9.1+` {applies_to}`serverless: ga` : Make the table more or less compact. Choose between **Compact**, **Normal** (default), and **Expanded**. ``` :::: @@ -278,9 +278,11 @@ Serverless at the time Elastic Stack 9.0.0 was released. Then, the functionality became generally available in Elastic Stack in 9.1.0 and shortly before the Elastic Stack 9.1.0 release in Serverless. -* For Elastic Stack, a versioned product, label the section with both lifecycles: `ga 9.1` and `preview 9.0`. * For Serverless, an unversioned product, update the section label from `serverless: preview` to `serverless: ga`. Do _not_ list both lifecycles. +* For Elastic Stack, a versioned product, label the section with both lifecycles: `ga 9.1+` and `preview =9.0`. + The latest released version is rendered in the badge and other lifecycle/versions is included in the popover attached to the badge. + Hover over the badge to see the popover. :::::{tab-set} ::::{tab-item} Image @@ -304,7 +306,7 @@ applies_to: ### Assign colors to terms [assign-colors-to-terms] ```{applies_to} -stack: ga 9.1+, preview =9.0, +stack: ga 9.1+, preview =9.0 serverless: ga ``` @@ -346,7 +348,7 @@ applies_to: security: all --- -# Configure advanced settings [security-advanced-settings] +# Configure advanced settings for Elastic Security [...] @@ -400,25 +402,52 @@ Using a code callout is the lightest-touch solution, but might not be sufficient :screenshot: :::: -### Solution B: Use tabs [code-block-tabs] +### Solution B: Use applies switch tabs [code-block-tabs] -:::{include} _snippets/applies-switch-and-tabs.md -::: - -**When to use tabs**: If using a [code callout](#code-block-callout) isn't appropriate. +**When to use applies switch tabs**: If using a [code callout](#code-block-callout) isn't appropriate. **Best practices**: * Try to minimize the number of tabs where possible, - but do not mix tabs and `applies_to`-related code callouts. + but do not mix applies switch and `applies_to`-related code callouts. * Try not to include information surrounding a code block in the tabs. Make the tab content as small as possible apart from the procedure itself. **Example**: On the [Upstream OpenTelemetry Collectors and language SDKs](https://www.elastic.co/docs/solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks#apm-connect-open-telemetry-collector) page, we use tabs to show two different code blocks: one for Serverless and one for Elastic Stack (stateful). +::::::{tab-set} +:::::{tab-item} Image ::::{image} ./images/example-code-block-tabs.png :screenshot: :::: +::::: + +:::::{tab-item} Code + +```` +Connect your OpenTelemetry Collector instances to Elastic {{observability}} +or {{obs-serverless}} using the OTLP exporter: + +::::{applies-switch} +:::{applies-item} stack: ga + +``` +[...] +``` + +::: +:::{applies-item} serverless: ga + +``` +[...] +``` + +::: +:::: +```` + +::::: +:::::: ## Workflows vary [workflow] @@ -442,18 +471,30 @@ but might not be sufficient in all cases. **Example**: Only one item in an ordered list varies between Serverless and stateful. -::::{image} ./images/workflow-inline.png +:::::{tab-set} + +::::{tab-item} Image +:::{image} ./images/workflow-inline.png :screenshot: +::: :::: -### Solution B: Use tabs [workflow-tabs] +::::{tab-item} Code +```md +1. Get started: + * {applies_to}`serverless: ga` In your {{obs-serverless}} project, go to **Add Data**. + * {applies_to}`stack: ga` In {{kib}}, go to the **Observability** UI and click **Add Data**. +1. Under **What do you want to monitor?** select **Host**, and then select **Elastic Agent: Logs & Metrics**. +1. Copy the install command. +``` +:::: +::::: -:::{include} _snippets/applies-switch-and-tabs.md -::: +### Solution B: Use applies switch tabs [workflow-tabs] -Tabs are minimally disruptive in many situations. +Applies switch tabs are minimally disruptive in many situations. -**When to use tabs**: +**When to use applies switch tabs**: * Using [inline `applies_to` badges](#workflow-inline) isn't appropriate. * All the tabs fit horizontally on a single row on a typical laptop screen. @@ -469,11 +510,43 @@ Tabs are minimally disruptive in many situations. Make the tab content as small as possible apart from the procedure itself. * Consider breaking up procedures into sets of procedures if only one section differs between contexts. -**Example**: On the [Enable audit logging](https://www.elastic.co/docs/deploy-manage/security/logging-configuration/enabling-audit-logs#enable-audit-logging-procedure) page, we use tabs to show separate ordered lists outlining the workflow for each deployment type. +**Example**: On the [Enable audit logging](https://www.elastic.co/docs/deploy-manage/security/logging-configuration/enabling-audit-logs#enable-audit-logging-procedure) page, we use applies switch tabs to show separate ordered lists outlining the workflow for each deployment type. +::::::{tab-set} + +:::::{tab-item} Image ::::{image} ./images/example-workflow-tabs.png :screenshot: :::: +::::: + +:::::{tab-item} Code + +``` +::::{applies-switch} + +:::{applies-item} ess: ga +[...] +::: + +:::{applies-item} eck: ga +[...] +::: + +:::{applies-item} ece: ga +[...] +::: + +:::{applies-item} self: ga +[...] +::: + +:::: +``` + +::::: + +:::::: ### Solution C: Use sibling pages [workflow-sibling-pages] @@ -481,7 +554,7 @@ Sibling pages are a last resort when no other solutions are appropriate. **When to use sibling pages**: -* Neither [inline `applies_to` badges](#workflow-inline) or [tabs](#workflow-tabs) are appropriate. +* Neither [inline `applies_to` badges](#workflow-inline) or [applies switch tabs](#workflow-tabs) are appropriate. * The workflow has significant differences across multiple procedures. * There are chained procedures where not all of the procedures are needed for all contexts or where the flow across procedures is muddied when versioning context is added. @@ -503,12 +576,9 @@ Sibling pages are a last resort when no other solutions are appropriate. Sometimes the UI differs between versions, deployment types or other conditions. -### Solution A: Use tabs [screenshot-tabs] - -:::{include} _snippets/applies-switch-and-tabs.md -::: +### Solution A: Use applies switch tabs [screenshot-tabs] -**When to use tabs**: +**When to use applies switch tabs**: * When the screenshot shows significantly different interfaces or workflows for each product, deployment type, or version. * When the screenshot represents a specific, interactive action, like clicking a button or navigating a UI that changes meaningfully between contexts. @@ -542,12 +612,9 @@ For example, versioning the screenshot on the [Dashboards](https://www.elastic.c ## Multiple adjacent block elements vary [multiple-block] -### Solution A: Use tabs [multiple-block-tabs] +### Solution A: Use applies switch tabs [multiple-block-tabs] -:::{include} _snippets/applies-switch-and-tabs.md -::: - -**When to use tabs**: +**When to use applies switch tabs**: * When the content is structurally similar but differs in detail — for example, slightly different instructions, outputs, or paths. * When you want to avoid repeating most of the surrounding content and isolate just the difference. @@ -571,13 +638,12 @@ _Work in progress._ ## Functionality is added to multiple patch versions [multiple-patch] -Sometimes, features and enhancements slip through into patch versions, and the same functionality might be added for the first time to multiple patch versions at the same time. +Sometimes, features and enhancements slip through into patch versions, and the same functionality might be added for the first time to multiple patch versions at the same time. - **Standard case**: Our docs are aligned with the latest patch of any given minor version. That means that in most cases, we don't need to call out the exact patch version that introduced a change (that's for the release notes). - - **Exceptions**: In rare cases, it can happen that the change is important enough to be explicitly called out in the docs with a precise patch-level information. In that case, you can add a callout and indicate patch-level versions using plain text to explain the change. -For example, on the [HTTP JSON input](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-httpjson) page, the `terminate` helper function was added to a 9.0.x and 9.1.x patch version at the same time. +For example, on the [HTTP JSON input](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-httpjson) page, the `terminate` helper function was added to a 9.0.x and 9.1.x patch version at the same time. Since the new functionality is available in the latest patch of both 9.0.x and 9.1.x, use the earlier version: 9.0.x. :::::{tab-set} ::::{tab-item} Image diff --git a/contribute-docs/how-to/cumulative-docs/guidelines.md b/contribute-docs/how-to/cumulative-docs/guidelines.md index ef3539cc04..cfe465ed50 100644 --- a/contribute-docs/how-to/cumulative-docs/guidelines.md +++ b/contribute-docs/how-to/cumulative-docs/guidelines.md @@ -7,10 +7,10 @@ navigation_title: Guidelines :::{note} This content is still in development. If you have questions about how to write cumulative documentation while contributing, -reach out to **@elastic/docs** in the related GitHub issue or PR. +reach out to **@elastic/docs** in the related GitHub issue or PR. ::: -Start by asking yourself: +To get started with cumulative docs, ask yourself: * Does this content vary between products, versions, or deployment types? * Is this a feature lifecycle change or just content improvement? @@ -44,9 +44,10 @@ For each type of applicability information, you can add `applies_to` metadata at This defines the overall applicability of the page across products and deployment models. * **Section-level** annotations allow you to specify different applicability for individual sections when only part of a page varies between products or versions. -% TO DO: Add when https://github.com/elastic/docs-builder/issues/1436 is complete -% * **Element-level** annotations allow tagging block-level elements like tabs, dropdowns, and admonitions. -% This is useful for ... +* **Element-level** annotations allow tagging block-level elements like tabs, dropdowns, and admonitions. + Choosing the right element can help communicate how to interpret applicability information. For example + tabs might indicate alternatives (only one tab is relevant to each user) and admonitions might indicate + that there is a notable exception to applicability in some context. * **Inline** annotations allow fine-grained annotations within paragraphs or lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. @@ -58,7 +59,7 @@ refer to [the applies_to syntax guide](https://elastic.github.io/docs-builder/sy ### When to tag content -Every page should include page-level `applies_to` tags to indicate which product or deployment type +Every page should include page-level `applies_to` tags to indicate which product or deployment type the content applies to. This is mandatory for every page. You should also generally tag content when: @@ -90,12 +91,10 @@ You generally do not need to tag: ### Tips -% Source: Slack conversation * **Consider how badges take up space on the page**: Avoid badge placement patterns that take up unnecessary Markdown real estate. For example, adding a dedicated column for applicability in a table when only a few rows require an `applies_to` badge. -% Source: George's checklist * **Use `unavailable` sparingly**: For example, if a page is only about Elastic Cloud Hosted, don't add a `serverless: unavailable` tag. Refer to [When to indicate something is NOT applicable](#when-to-indicate-something-is-not-applicable) for specific guidance. @@ -106,26 +105,30 @@ You generally do not need to tag: Sometimes features GA for one deployment but remain preview for another. * **Think across time**: Product lifecycle changes with each release. - Even if a feature might be deprecated or legacy in one deployment it may still be supported elsewhere. -* **For updates, remember they may be older than you think**: - Some updates that may be required to the documentation could precede v9.0. + Even if a feature might be deprecated or legacy in one deployment it might still be supported elsewhere. +* **For updates, remember they might be older than you think**: + Some updates that might be required to the documentation could precede v9.0. For these changes need to be made to the old AsciiDoc versions of the content. -% TO DO: Update when the PRs that auto-sort order are merged -% Maybe move to the "how dynamic tagging works"? -## Order of items +## Order of items [order-of-items] -### Versions +### Versions [order-versions] When listing multiple versions, author the newest version first whenever possible. This keeps files consistent and easier to maintain. -Regardless of the source file, the build system automatically builds badge lifecycles in reverse chronological order. -This means that badges will always appear to users from newest to oldest, which is the reverse of the product development timeline. +Regardless of the source file, the build system automatically renders badge lifecycles in reverse chronological order. +This means that badges always appear to users from newest to oldest, which is the reverse of the product development timeline. -For example: +For example this syntax: + +``` +{applies_to}`stack: preview =9.0, beta =9.1, ga 9.2+` +``` + +Results in this badge: {applies_to}`stack: preview =9.0, beta =9.1, ga 9.2+` -### Keys +### Keys [order-keys] The build system automatically orders multiple [keys](reference.md#key) in a consistent pattern. This reduces authoring overhead and makes content easier for users to scan. @@ -139,8 +142,9 @@ Keys are ordered as follows: 2. **Deployment types**: ECH (Elastic Cloud Hosted), ECK (Elastic Cloud on Kubernetes), ECE (Elastic Cloud Enterprise), Self-Managed 3. **ProductApplicability**: ECCTL, Curator, EDOT items (alphabetically), APM Agent items (alphabetically) -For example: +For example this syntax: +```` ```{applies_to} deployment: ece: ga @@ -148,6 +152,11 @@ deployment: stack: ga serverless: ga ``` +```` + +Results in the badges in this order: + +{applies_to}`{ deployment: { ece: ga, self: ga }, stack: ga, serverless: ga }` ## Product and deployment model applicability [products-and-deployment-models] @@ -172,9 +181,8 @@ Here are some common scenarios you might come across: * Content is about both Elastic Stack components and the Serverless UI. ([example](example-scenarios.md#stateful-serverless)) -* Content is primarily about orchestrating, deploying or configuring an installation. - % TO DO: Add example - % ([example](example-scenarios.md#)) +* Content is primarily about orchestrating, deploying, or configuring an installation. + ([example](example-scenarios.md#workflow-tabs)) * Content is primarily about a product following its own versioning schema. % TO DO: Add example % ([example](example-scenarios.md#)) @@ -253,8 +261,7 @@ For versioned products like the Elastic Stack: #### Mixed versioned and unversioned products [mixed] -* When documenting features shared between serverless and Elastic Stack, - ... +* When documenting features shared between serverless and Elastic Stack ([example](example-scenarios.md#stateful-serverless)). * When a feature in an unversioned product is removed, but the content also applies to another context (for example a feature is removed in both Kibana 9.x and Serverless), @@ -269,7 +276,7 @@ For example, a page describing how to create an {{ech}} deployment just requires This is true for most situations. However, it can still be useful to call it out in a few specific scenarios: -* When there is a high risk of confusion for users. This may be subjective, but let’s imagine a scenario where a feature is available in 2 out of 3 serverless project types. It may make sense to clarify and be explicit about the feature being “unavailable” for the 3rd type. For example: +* **When there is a high risk of confusion for users**. For example, if a feature is available in two out of three serverless project types, it might make sense to clarify and be explicit about the feature being “unavailable” for the third type. ```yml --- @@ -283,7 +290,8 @@ This is true for most situations. However, it can still be useful to call it out ``` -* When a specific section, paragraph or list item has specific applicability that differs from the context set at the page or section level, and the action is not possible at all for that context (meaning that there is no alternative). For example: +* **When only one section, paragraph, or element describes functionality that is unavailable in the context set at a higher level**. + For example, if a page is largely applicable to both `serverless` and `stack`, but one section describes functionality that is not possible in serverless (and there is no alternative). ````md --- diff --git a/contribute-docs/how-to/cumulative-docs/images/definition-list-portion-correct.png b/contribute-docs/how-to/cumulative-docs/images/definition-list-portion-correct.png index ae0d270173..e54ebfe7eb 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/definition-list-portion-correct.png and b/contribute-docs/how-to/cumulative-docs/images/definition-list-portion-correct.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/example-code-block-callout.png b/contribute-docs/how-to/cumulative-docs/images/example-code-block-callout.png index 45baa8fb83..74a801ea34 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/example-code-block-callout.png and b/contribute-docs/how-to/cumulative-docs/images/example-code-block-callout.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/example-code-block-tabs.png b/contribute-docs/how-to/cumulative-docs/images/example-code-block-tabs.png index 935bd23e8e..934bba3ff2 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/example-code-block-tabs.png and b/contribute-docs/how-to/cumulative-docs/images/example-code-block-tabs.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/example-lifecycle-changed.png b/contribute-docs/how-to/cumulative-docs/images/example-lifecycle-changed.png index 5dfcf339cd..2da03411e5 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/example-lifecycle-changed.png and b/contribute-docs/how-to/cumulative-docs/images/example-lifecycle-changed.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/example-multiple-patch.png b/contribute-docs/how-to/cumulative-docs/images/example-multiple-patch.png index 369f555cde..19d76f2f43 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/example-multiple-patch.png and b/contribute-docs/how-to/cumulative-docs/images/example-multiple-patch.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/example-removed-unversioned-exception.png b/contribute-docs/how-to/cumulative-docs/images/example-removed-unversioned-exception.png index 3013b09bbf..bffa588d6d 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/example-removed-unversioned-exception.png and b/contribute-docs/how-to/cumulative-docs/images/example-removed-unversioned-exception.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/example-unversioned-added-same-exception.png b/contribute-docs/how-to/cumulative-docs/images/example-unversioned-added-same-exception.png index 0c8b0dfcbc..0d5c692154 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/example-unversioned-added-same-exception.png and b/contribute-docs/how-to/cumulative-docs/images/example-unversioned-added-same-exception.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/example-workflow-tabs.png b/contribute-docs/how-to/cumulative-docs/images/example-workflow-tabs.png index 05aa314a30..a9be9a373a 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/example-workflow-tabs.png and b/contribute-docs/how-to/cumulative-docs/images/example-workflow-tabs.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/heading-correct.png b/contribute-docs/how-to/cumulative-docs/images/heading-correct.png index 3dcb5eb765..be4e726ecf 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/heading-correct.png and b/contribute-docs/how-to/cumulative-docs/images/heading-correct.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/list-correct.png b/contribute-docs/how-to/cumulative-docs/images/list-correct.png index 2483fd0c02..698846d959 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/list-correct.png and b/contribute-docs/how-to/cumulative-docs/images/list-correct.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/list-misc-correct.png b/contribute-docs/how-to/cumulative-docs/images/list-misc-correct.png deleted file mode 100644 index e6da7a477f..0000000000 Binary files a/contribute-docs/how-to/cumulative-docs/images/list-misc-correct.png and /dev/null differ diff --git a/contribute-docs/how-to/cumulative-docs/images/page-section-varies-deployment.png b/contribute-docs/how-to/cumulative-docs/images/page-section-varies-deployment.png index a7e7a2d0a7..1103b6567c 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/page-section-varies-deployment.png and b/contribute-docs/how-to/cumulative-docs/images/page-section-varies-deployment.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/page-section-varies-product.png b/contribute-docs/how-to/cumulative-docs/images/page-section-varies-product.png index 14a01089be..d85a83d83d 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/page-section-varies-product.png and b/contribute-docs/how-to/cumulative-docs/images/page-section-varies-product.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/reader-experience.png b/contribute-docs/how-to/cumulative-docs/images/reader-experience.png index 4e44279be4..dae8442fbb 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/reader-experience.png and b/contribute-docs/how-to/cumulative-docs/images/reader-experience.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/table-entire-row-correct.png b/contribute-docs/how-to/cumulative-docs/images/table-entire-row-correct.png index 3cc9796527..f8e05ed40c 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/table-entire-row-correct.png and b/contribute-docs/how-to/cumulative-docs/images/table-entire-row-correct.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/table-part-of-cell-correct.png b/contribute-docs/how-to/cumulative-docs/images/table-part-of-cell-correct.png index 15c4448375..4cba36f045 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/table-part-of-cell-correct.png and b/contribute-docs/how-to/cumulative-docs/images/table-part-of-cell-correct.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/workflow-inline.png b/contribute-docs/how-to/cumulative-docs/images/workflow-inline.png index 53f23f676a..a1a2694818 100644 Binary files a/contribute-docs/how-to/cumulative-docs/images/workflow-inline.png and b/contribute-docs/how-to/cumulative-docs/images/workflow-inline.png differ diff --git a/contribute-docs/how-to/cumulative-docs/index.md b/contribute-docs/how-to/cumulative-docs/index.md index 446baad3d8..53821eb151 100644 --- a/contribute-docs/how-to/cumulative-docs/index.md +++ b/contribute-docs/how-to/cumulative-docs/index.md @@ -3,7 +3,7 @@ :::{note} This content is still in development. If you have questions about how to write cumulative documentation while contributing, -reach out to **@elastic/docs** in the related GitHub issue or PR. +reach out to **@elastic/docs** in the related GitHub issue or PR. ::: In [elastic.co/docs](https://elastic.co/docs) (Docs V3) we write docs cumulatively. This means that in 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. @@ -11,12 +11,12 @@ In [elastic.co/docs](https://elastic.co/docs) (Docs V3) we write docs cumulative :::{important} 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. -Nothing changes for our ASCIIDoc-based documentation system, that remains published and maintained for the following versions: Elastic Stack until 8.x, ECE until 3.x, ECK until 2.x, etc. +Nothing changes for our AsciiDoc-based documentation system, that remains published and maintained for the following versions: Elastic Stack until 8.x, ECE until 3.x, ECK until 2.x, etc. ::: ## Reader experience -With cumulative documentation, when a user arrives in our documentation from an outside source, they land on a page that is a single source of truth. This means it will be more likely that the page they land on contains content that applies to them regardless of which version or deployment type they are using. +With cumulative documentation, when a user arrives in our documentation from an outside source, they land on a page that is a single source of truth. This means it is more likely that the page they land on contains content that applies to them regardless of which version or deployment type they are using. Users can then compare and contrast differences on a single page to understand what is available to them and explore the ways certain offerings might improve their experience. @@ -27,7 +27,7 @@ Users can then compare and contrast differences on a single page to understand w ## Contributor experience -With cumulative documentation, there is a single "source of truth" for each feature, which helps us to maintain consistency, accuracy, and maintainability of our documentation over time, and avoids "drift" between multiple similar sets of documentation. +With cumulative documentation, there is a single "source of truth" for each feature, which helps with consistency, accuracy, and maintainability of our documentation over time. It also avoids "drift" between multiple similar sets of documentation. 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. @@ -46,7 +46,7 @@ You should also generally tag content when: * Functionality changes state, like going from beta to GA * Availability varies, like being available in Elastic Cloud Enterprise but not in Elastic Cloud Hosted -**For detailed guidance on contributing to cumulative docs, refer to [guidelines.md](guidelines.md).** +**For detailed guidance on contributing to cumulative docs, refer to [](guidelines.md).** ### When _not_ to tag content diff --git a/contribute-docs/locally.md b/contribute-docs/locally.md index 589f890093..59e80d2e3e 100644 --- a/contribute-docs/locally.md +++ b/contribute-docs/locally.md @@ -108,7 +108,7 @@ We write docs in Markdown. Refer to our [syntax quick reference](syntax-quick-re 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](how-to/cumulative-docs/index.md). -:::{include} _snippets-contribute/tagged-warning.md +:::{include} _snippets/tagged-warning.md ::: ## Build the docs diff --git a/contribute-docs/on-the-web.md b/contribute-docs/on-the-web.md index dba0ca1d8e..797b03deff 100644 --- a/contribute-docs/on-the-web.md +++ b/contribute-docs/on-the-web.md @@ -29,7 +29,7 @@ An Elastician will review, merge, and propagate your change to the right places For more details on editing files on GitHub, refer to [GitHub's documentation on editing files](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files). -:::{include} _snippets-contribute/tagged-warning.md +:::{include} _snippets/tagged-warning.md ::: ## Editing `elastic.co/guide` docs (Asciidoc) diff --git a/get-started/howto-use-the-docs.md b/get-started/howto-use-the-docs.md index 8f0d9839da..cb148872a9 100644 --- a/get-started/howto-use-the-docs.md +++ b/get-started/howto-use-the-docs.md @@ -9,15 +9,15 @@ Our documentation is organized to guide you through your journey with Elastic, f Here is a detailed breakdown of the documentation structure: -* [**Elastic fundamentals**](/get-started/index.md): Understand the basics about the deployment options, platform, solutions, and features of the documentation. -* [**Solutions and use cases**](/solutions/index.md): Learn use cases, evaluate, and implement Elastic's solutions: Observability, Search, and Security. -* [**Manage data**](/manage-data/index.md): Learn about data store primitives, ingestion and enrichment, managing the data lifecycle, and migrating data. -* [**Explore and analyze**](/explore-analyze/index.md): Get value from data through querying, visualization, machine learning, and alerting. -* [**Deploy and manage**](/deploy-manage/index.md): Deploy and manage production-ready clusters. Covers deployment options and maintenance tasks. -* [**Manage your Cloud account**](/cloud-account/index.md): A dedicated section for user-facing cloud account tasks like resetting passwords. -* [**Troubleshoot**](/troubleshoot/index.md): Identify and resolve problems. -* [**Extend and contribute**](/extend/index.md): How to contribute to or integrate with Elastic, from open source to plugins to integrations. -* [**Release notes**](/release-notes/index.md): Contains release notes and changelogs for each new release. +* [**Elastic fundamentals**](/get-started/index.md): Understand the basics about the deployment options, platform, solutions, and features of the documentation. +* [**Solutions and use cases**](/solutions/index.md): Learn use cases, evaluate, and implement Elastic's solutions: Observability, Search, and Security. +* [**Manage data**](/manage-data/index.md): Learn about data store primitives, ingestion and enrichment, managing the data lifecycle, and migrating data. +* [**Explore and analyze**](/explore-analyze/index.md): Get value from data through querying, visualization, machine learning, and alerting. +* [**Deploy and manage**](/deploy-manage/index.md): Deploy and manage production-ready clusters. Covers deployment options and maintenance tasks. +* [**Manage your Cloud account**](/cloud-account/index.md): A dedicated section for user-facing cloud account tasks like resetting passwords. +* [**Troubleshoot**](/troubleshoot/index.md): Identify and resolve problems. +* [**Extend and contribute**](/extend/index.md): How to contribute to or integrate with Elastic, from open source to plugins to integrations. +* [**Release notes**](/release-notes/index.md): Contains release notes and changelogs for each new release. * [**Reference**](/reference/index.md): Reference material for core tasks and manuals for other Elastic products. ## Applicability badges @@ -36,62 +36,21 @@ A **Stack** badge indicates that a page applies to [{{stack}}](/get-started/the- On each documentation page, you can find several links that allow you to interact with the content: -* **View as Markdown**: This link shows you the raw Markdown source code for the page you're viewing. This can be helpful if you want to reuse the source or feed the document to AI. -* **Edit this page**: Selecting this link will take you directly to the page's source file in its GitHub repository. From there, you can propose edits, which our team will review. +* **View as Markdown**: This link shows you the raw Markdown source code for the page you're viewing. This can be helpful if you want to reuse the source or feed the document to AI. +* **Edit this page**: Selecting this link will take you directly to the page's source file in its GitHub repository. From there, you can propose edits, which our team will review. * **Report an issue**: If you've found a problem, like a typo, a technical error, or confusing content, but don't want to edit the page yourself, use this link. It will open a new issue in our GitHub repository, pre-filled with information about the page you were on, so you can describe the problem in detail. ## Versioned documentation Starting with {{stack}} 9.0, Elastic no longer publishes separate documentation sets for each minor release. Instead, all changes in the 9.x series are included in a single, continuously updated documentation set. -This approach helps: - -* Reduce duplicate pages. -* Show the full history and context of a feature. -* Simplify search and navigation. - -We clearly mark content added or changed in a specific version using availability badges. The availability badges appear in page headers, section headers, and inline. - -### Elastic Stack example - -{applies_to}`stack: ga 9.1.0` - -This means the feature is: - -* Generally Available (GA) in the [{{stack}}](/get-started/the-stack.md) across all deployment options except {{serverless-full}} -* Introduced in version 9.1.0 - -:::{tip} -If a page applies to all deployment options including {{serverless-full}}, it will have both {{serverless-short}} and Stack badges. -::: - -### Serverless example - -{applies_to}`serverless: ga` {applies_to}`security: beta` - -This means the feature is: - -* Generally Available for {{es-serverless}} projects -* Beta for {{sec-serverless}} projects - -### Elastic Cloud Enterprise example - -{applies_to}`ece: deprecated 4.1.0` - -This means the feature is: - -* Available on Elastic Cloud Enterprise -* Deprecated starting in version 4.1.0 - -:::{tip} -Want to learn more about how availability badges are used? Check the [Elastic Docs syntax guide](https://elastic.github.io/docs-builder/syntax/applies/). -::: +Read more in [](versioning-availability.md). ## Accessing previous versions You can browse documentation for different versions of our products in two ways: -* **Version menu:** On most documentation pages, you'll find a version menu. Clicking this menu allows you to switch to a different version of the documentation for the content you are currently viewing. +* **Version menu:** On most documentation pages, you'll find a version menu. Clicking this menu allows you to switch to a different version of the documentation for the content you are currently viewing. * **All documentation versions page:** For a complete list of all available documentation versions for all Elastic products, you can visit the [All documentation versions](/versions.md) page. ## Glossary diff --git a/get-started/versioning-availability.md b/get-started/versioning-availability.md index 457b186368..a13096cb5f 100644 --- a/get-started/versioning-availability.md +++ b/get-started/versioning-availability.md @@ -45,7 +45,7 @@ stack: ga 9.1 This means the feature is: * Available on {{stack}} * Generally Available (GA) -* Introduced in version 9.1.0 +* Introduced in version 9.1 #### Serverless example @@ -63,12 +63,12 @@ This means the feature is: ```{applies_to} deployment: - ece: deprecated 4.1.0 + ece: deprecated 4.0+ ``` This means the feature is: * Available on {{ece}} -* Deprecated starting in version 4.1.0 +* Deprecated starting in version 4.0 :::{tip} Want to learn more about how we use availability badges? Check out the [Elastic Docs syntax guide](https://elastic.github.io/docs-builder/syntax/applies/).