diff --git a/contribute-docs/_snippets-contribute/guide-intro.md b/contribute-docs/_snippets-contribute/guide-intro.md new file mode 100644 index 0000000000..2c1177ab64 --- /dev/null +++ b/contribute-docs/_snippets-contribute/guide-intro.md @@ -0,0 +1,3 @@ +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 new file mode 100644 index 0000000000..8b9fd2e67a --- /dev/null +++ b/contribute-docs/_snippets-contribute/tag-processing.md @@ -0,0 +1,26 @@ +`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/tagged-warning.md b/contribute-docs/_snippets-contribute/tagged-warning.md new file mode 100644 index 0000000000..8e9d2e08fa --- /dev/null +++ b/contribute-docs/_snippets-contribute/tagged-warning.md @@ -0,0 +1,7 @@ +:::{warning} +Some repositories use a [tagged branching strategy](https://elastic.github.io/docs-builder/contribute/branching-strategy/), 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 branching strategy for a repository](https://elastic.github.io/docs-builder/contribute/branching-strategy/#workflow-2-tagged). + +To determine the published branches for a repository, find the repository in [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml). +::: diff --git a/contribute-docs/_snippets-contribute/two-systems.md b/contribute-docs/_snippets-contribute/two-systems.md new file mode 100644 index 0000000000..ae48c4e1b5 --- /dev/null +++ b/contribute-docs/_snippets-contribute/two-systems.md @@ -0,0 +1,7 @@ +Because the new documentation site only hosts documentation for newer releases, the way that you contribute depends on the version that you want to document. + +For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs) (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-key.md b/contribute-docs/_snippets/applies_to-key.md new file mode 100644 index 0000000000..ebf9776090 --- /dev/null +++ b/contribute-docs/_snippets/applies_to-key.md @@ -0,0 +1,37 @@ +`applies_to` accepts the following keys in this structure. + +* `serverless`: Applies to [Elastic Cloud Serverless](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/serverless). + * `security`: Applies to Serverless [security projects](https://www.elastic.co/docs/solutions/security/get-started/create-security-project). + * `elasticsearch`: Applies to Serverless [search projects](https://www.elastic.co/docs/solutions/search/serverless-elasticsearch-get-started). + * `observability`: Applies to Serverless [observability projects](https://www.elastic.co/docs/solutions/observability/get-started). +* `stack`: Applies to the [Elastic Stack](https://www.elastic.co/docs/get-started/the-stack) including any Elastic Stack components. +* `deployment`: Applies to some deployment type(s). + * `ece`: Applies to [Elastic Cloud Enterprise](https://www.elastic.co/docs/deploy-manage/deploy/cloud-enterprise) deployments. + * `eck`: Applies to [Elastic Cloud on Kubernetes](https://www.elastic.co/docs/deploy-manage/deploy/cloud-on-k8s) deployments. + * `self`: Applies to [self-managed](https://www.elastic.co/docs/deploy-manage/deploy/self-managed) deployments. + * `ess`: Applies to [Elastic Cloud Hosted](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/cloud-hosted) deployments. +* `product`: Applies to a specific product that uses a unique versioning scheme (for example, not `stack`, `ece`, `eck`). + * `apm_agent_dotnet`: Applies to the [Elastic APM .NET agent](https://www.elastic.co/docs/reference/apm/agents/dotnet). + * `apm_agent_go`: Applies to the [Elastic APM Go agent](https://www.elastic.co/docs/reference/apm/agents/go). + * `apm_agent_java`: Applies to the [Elastic APM Java agent](https://www.elastic.co/docs/reference/apm/agents/java). + * `apm_agent_node`: Applies to the [Elastic APM Node.js agent](https://www.elastic.co/docs/reference/apm/agents/nodejs). + * `apm_agent_php`: Applies to the [Elastic APM PHP agent](https://www.elastic.co/docs/reference/apm/agents/php). + * `apm_agent_python`: Applies to the [Elastic APM Python agent](https://www.elastic.co/docs/reference/apm/agents/python). + * `apm_agent_ruby`: Applies to the [Elastic APM Ruby agent](https://www.elastic.co/docs/reference/apm/agents/ruby). + * `apm_agent_rum`: Applies to the [APM RUM JavaScript agent](https://www.elastic.co/docs/reference/apm/agents/rum-js). + * `curator`: Applies to [Elasticsearch Curator](https://www.elastic.co/docs/reference/elasticsearch/curator) (Curator). + * `ecctl`: Applies to [Elastic cloud control](https://www.elastic.co/docs/reference/ecctl) (ECCTL). + * `edot_android`: Applies to the [Elastic Distribution of OpenTelemetry Android](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/android/) (EDOT Android). + * `edot_cf_aws`: Applies to the [Elastic Distribution of OpenTelemetry Cloud Forwarder](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/) (EDOT Cloud Forwarder). + * `edot_cf_azure`: Applies to the [Elastic Distribution of OpenTelemetry Cloud Forwarder](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/) (EDOT Cloud Forwarder). + * `edot_collector`: Applies to the [Elastic Distribution of OpenTelemetry Collector](https://www.elastic.co/docs/reference/opentelemetry/edot-collector/) (EDOT Collector). + * `edot_dotnet`: Applies to the [Elastic Distribution of OpenTelemetry .NET](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/dotnet/) (EDOT .NET). + * `edot_ios`: Applies to the [Elastic Distribution of OpenTelemetry iOS](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/ios/) (EDOT iOS). + * `edot_java`: Applies to the [Elastic Distribution of OpenTelemetry Java](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/java/) (EDOT Java). + * `edot_node`: Applies to the [Elastic Distribution of OpenTelemetry Node.js](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/nodejs/) (EDOT Node.js). + * `edot_php`: Applies to the [Elastic Distribution of OpenTelemetry PHP](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/php/) (EDOT PHP). + * `edot_python`: Applies to the [Elastic Distribution of OpenTelemetry Python](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/python/) (EDOT Python). + +:::{note} +The `product` key and its subkeys are used to indicate feature availability and applicability. The similarly named [`products` frontmatter field](https://elastic.github.io/docs-builder/syntax/frontmatter#products) is used to drive elastic.co search filters. +::: diff --git a/contribute-docs/_snippets/applies_to-lifecycle.md b/contribute-docs/_snippets/applies_to-lifecycle.md new file mode 100644 index 0000000000..439613d3cc --- /dev/null +++ b/contribute-docs/_snippets/applies_to-lifecycle.md @@ -0,0 +1,8 @@ +`applies_to` accepts the following lifecycle states: + +* `preview` +* `beta` +* `ga` +* `deprecated` +* `removed` +* `unavailable` \ No newline at end of file diff --git a/contribute-docs/_snippets/applies_to-version.md b/contribute-docs/_snippets/applies_to-version.md new file mode 100644 index 0000000000..f98f758d04 --- /dev/null +++ b/contribute-docs/_snippets/applies_to-version.md @@ -0,0 +1,10 @@ +`applies_to` accepts the following version formats: + +* `Major.Minor` +* `Major.Minor.Patch` + +Regardless of the version format used in the source file, the version number is always rendered in the `Major.Minor.Patch` format. + +:::{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: ga 8.18.6, ga 9.1.2, ga 8.19.2, ga 9.0.6` will be displayed as `stack: ga 9.1.2, ga 9.0.6, ga 8.19.2, ga 8.18.6`. Items without versions (like `ga` without a version or `all`) are sorted last. +::: \ No newline at end of file diff --git a/contribute-docs/_snippets/sample-data.csv b/contribute-docs/_snippets/sample-data.csv new file mode 100644 index 0000000000..32dfb0c6f4 --- /dev/null +++ b/contribute-docs/_snippets/sample-data.csv @@ -0,0 +1,6 @@ +Name,Age,City,Occupation +John Doe,30,New York,Software Engineer +Jane Smith,25,Los Angeles,Product Manager +Bob Johnson,35,Chicago,Data Scientist +Alice Brown,28,San Francisco,UX Designer +Charlie Wilson,32,Boston,DevOps Engineer diff --git a/contribute-docs/_snippets/stack-serverless-lifecycle-example.md b/contribute-docs/_snippets/stack-serverless-lifecycle-example.md new file mode 100644 index 0000000000..b0cfc667bb --- /dev/null +++ b/contribute-docs/_snippets/stack-serverless-lifecycle-example.md @@ -0,0 +1,21 @@ +If a change is released in Serverless and will be released in a future version of the {{stack}}, you can add both a `serverless` and `stack` tag, indicating the version of the {{stack}} in which the feature will be released: + +``` +--- +applies_to: + serverless: ga + stack: ga 9.2 +--- +``` + +Because these changes need to be published as soon as the feature is released in Serverless, you might need to publish your docs before the feature is available in the {{stack}}. To allow for this, Docs V3 [displays badges differently](/contribute-docs/how-to/cumulative-docs/index.md#how-do-these-tags-behave-in-the-output) when the `applies_to` tag specifies a product version that has not yet been released to customers. + +* A feature is tagged as available in a current Serverless release and a future {{stack}} version will render the following badges: + + {applies_to}`serverless: ga` + {applies_to}`stack: ga 99.99` + +* After the {{stack}} version is released, the same badges will render with the version number without any changes to the badge value in the source. + + {applies_to}`serverless: ga` + {applies_to}`stack: ga 9.0` \ No newline at end of file diff --git a/contribute-docs/_snippets/tag-processing.md b/contribute-docs/_snippets/tag-processing.md new file mode 100644 index 0000000000..8b9fd2e67a --- /dev/null +++ b/contribute-docs/_snippets/tag-processing.md @@ -0,0 +1,26 @@ +`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/asciidoc-guide.md b/contribute-docs/asciidoc-guide.md new file mode 100644 index 0000000000..55ad847b5a --- /dev/null +++ b/contribute-docs/asciidoc-guide.md @@ -0,0 +1,41 @@ +--- +navigation_title: Contribute to Asciidoc docs +--- + +# Contribute to `elastic.co/guide` (Asciidoc) + +To contribute to pages that live at [elastic.co/guide](https://www.elastic.co/guide/index.html), you must work with our [Asciidoc documentation build system](https://github.com/elastic/docs). These docs are written in the [ASCIIDoc](https://asciidoc.org/) markup language. + +Refer to [elastic.co/guide](https://www.elastic.co/guide) for the full list of products and versions that use this system. + +## Contribute on the web + +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 as required by the repo. To learn which labels to add, refer to the contribution documentation for that repo or reach out to the file codeowners. + +:::{note} +Backports can be complicated. You can use the [backport tool](https://github.com/sorenlouv/backport) to manage backporting your changes to other version branches. +::: + +## Contribute locally + +For complex or multi-page updates to `elastic.co/guide` (Asciidoc) documentation, refer to the [Asciidoc documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation). + +## Updating docs in both systems + +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 /docs content first in Markdown as described in [Contribute on the web](on-the-web.md) 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 [Contribute on the web](#contribute-on-the-web) 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 (if applicable) once the updates are reflected in the documentation. diff --git a/contribute-docs/how-to/cumulative-docs/_snippets/applies-switch-and-tabs.md b/contribute-docs/how-to/cumulative-docs/_snippets/applies-switch-and-tabs.md new file mode 100644 index 0000000000..9f594d8c20 --- /dev/null +++ b/contribute-docs/how-to/cumulative-docs/_snippets/applies-switch-and-tabs.md @@ -0,0 +1,6 @@ +:::{tip} - Use applies-switch instead of traditional tabs + +When you'd like to build a tabbed experience for content that varies specifically between two or more versions, or between two or more deployment types, prefer using [applies-switch](https://elastic.github.io/docs-builder/syntax/applies-switch) over regular [tabs](https://elastic.github.io/docs-builder/syntax/tabs). + +**Applies-switch** natively support using `applies_to` metadata keys as tab titles and offer a more consistent experience with recognizable badges. +::: \ No newline at end of file diff --git a/contribute-docs/how-to/cumulative-docs/_snippets/content-patterns-list.md b/contribute-docs/how-to/cumulative-docs/_snippets/content-patterns-list.md new file mode 100644 index 0000000000..9b54ae8eda --- /dev/null +++ b/contribute-docs/how-to/cumulative-docs/_snippets/content-patterns-list.md @@ -0,0 +1,11 @@ +% | Approach | Use case | +% | --- | --- | +% | [Page-level `applies` tags](/versions/example-scenarios.md#page-level-applies-tags) | Provide signals that a page applies to the reader. | +% | [Section/heading-level `applies` tags](/versions/example-scenarios.md#sectionheading-level-applies-tags) | Provide signals about a section’s scope so a user can choose to read or skip it as needed. | +% | [Tabs](/versions/example-scenarios.md#tabs) | Provide two sets of procedures when one or more steps in a process differs between contexts or versions. | +% | [Callouts](/versions/example-scenarios.md#callouts) | Draw attention to happy differences and basic clarifications. | +% | [Prose](/versions/example-scenarios.md#prose) | - Identify features in a list of features that are exclusive to a specific context, or that were introduced in a specific version
- List differing requirements, limits, and other simple, mirrored facts
- Provide clarifying or secondary information
- Explain differences with a "why" (e.g. comparative overviews) | +% | [Sibling pages](/versions/example-scenarios.md#sibling-pages) | When the information is too complex to be addressed with only the other content patterns. See specific examples in the sibling pages section. | + +% | [List item suffixes](/versions/example-scenarios.md#list-item-suffixes) | Identify features in a **list of features** that are exclusive to a specific context, or that were introduced in a specific version. | +% | [Sibling bullets](/versions/example-scenarios.md#sibling-bullets) | List differing requirements, limits, and other simple, mirrored facts. | \ No newline at end of file diff --git a/contribute-docs/how-to/cumulative-docs/badge-placement.md b/contribute-docs/how-to/cumulative-docs/badge-placement.md new file mode 100644 index 0000000000..19cd37e9f6 --- /dev/null +++ b/contribute-docs/how-to/cumulative-docs/badge-placement.md @@ -0,0 +1,198 @@ +# Badge usage and placement + +:::{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. +::: + +As you continue contributing to documentation and more versions are released, +you might have questions about how to integrate `applies_to` badges in +cumulative documentation. + +## Use cases + +Depending on what you're trying to communicate, you can use the following patterns to represent +version and deployment type differences in your docs: + +* **Pages**: Provide signals that a page applies to the reader. +* **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. +* **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. +* Consider scanning patterns - readers often scan for relevant information. +* Ensure badges don't break the natural flow of content. +* Use consistent placement patterns within similar content types. +* Consider visual grouping - readers must naturally associate the badge with its corresponding content, no more, no less. + +## Placement in specific elements + +There are more specific guidelines on badge placement to follow when using specific elements. + +### Page frontmatter + +Use [`applies_to` in a page's frontmatter](https://elastic.github.io/docs-builder/syntax/applies#syntax) to provide signals that a page applies to the reader. + +::::{warning} +Do **not** use [section-level](https://elastic.github.io/docs-builder/syntax/applies#section-level) or [inline annotations](https://elastic.github.io/docs-builder/syntax/applies#inline-level) with the page title. +:::: + +### Headings [headings] + +Use [section annotations](https://elastic.github.io/docs-builder/syntax/applies#section-level) on the next line after a heading when the entire content between that heading and the next [heading](https://elastic.github.io/docs-builder/syntax/headings) of the same or higher level is version or product-specific. + +For example, on the [Observability AI Assistant](https://www.elastic.co/docs/solutions/observability/observability-ai-assistant#choose-the-knowledge-base-language-model) page, all the content in this section is only applicable to Elastic Stack versions 9.1.0 and later. + +::::{image} ./images/heading-correct.png +:screenshot: +:alt: Correct use of applies_to with headings +:::: + +% FOR THE REVIEWER: IS THIS TRUE? +% What do you think of allowing inline applies_to in headings as long as there is only one badge? +:::{warning} +Do **not** use [inline annotations](https://elastic.github.io/docs-builder/syntax/applies#inline-level) with headings. + +::::{image} ./images/heading-incorrect.png +:screenshot: +:alt: Rendering error when using inline applies_to with headings +:::: +::: + +### Ordered and unordered lists [ordered-and-unordered-lists] + +Reorganize content as needed so the `applies_to` badge is relevant to the entire contents of the list item. +This could mean distinguishing between deployment types, products, lifecycles, or versions. +Placing the badge at the beginning of the list item, allows the reader to scan the list for the item that is relevant to them. + +For example, the [Alerting and action settings in Kibana](https://www.elastic.co/docs/reference/kibana/configuration-reference/alerting-settings) page lists how the default value for the `xpack.actions.preconfigured..config.defaultModel` setting varies in Serverless/Stack and across versions. + +::::{image} ./images/list-correct.png +:screenshot: +:alt: +:::: + +### Definition lists [definition-lists] + +The recommended placement of `applies_to` badges in definition lists varies based on what part(s) of the list item relate to the badge. + +#### If the badge is relevant to the entire contents of a list item, put it at the end of the term [definition-list-item-full] + +This means using an inline annotation at the end of the same line as the term. For example, on the Kibana [Advanced settings](https://www.elastic.co/docs/reference/kibana/advanced-settings#kibana-banners-settings) page, the entire `banners:linkColor` option is only available in Elastic Stack 9.1.0 and later. + +:::{image} ./images/definition-list-entire-item.png +:screenshot: +:alt: Correct use of applies_to with definition list item +::: + +:::{warning} +Do **not** put the `applies_to` badge at the beginning or end of the definition if it relates to the entire contents of the item. + +::::{image} ./images/definition-list-item-incorrect.png +:screenshot: +:alt: Incorrectly using inline applies_to with a definition list item +:::: +::: + +#### If the badge is only relevant to a portion of the definition, follow the appropriate placement guidelines for the elements used in the definition [definition-list-item-part] + +This might include labeling just one of multiple paragraphs, or one item in an ordered or unordered list. For example, on the [Google Gemini Connector page](https://www.elastic.co/docs/reference/kibana/connectors-kibana/gemini-action-type#gemini-connector-configuration), the default model is different depending on the deployment type and version of the Elastic Stack. These differences should be called out with their own `applies_to` badges. + +In this example, the `applies_to` badges should be at the beginning of each list item as described in [the guidelines for lists](#ordered-and-unordered-lists). + +::::{image} ./images/definition-list-portion-correct.png +:screenshot: +:alt: Correctly using inline applies_to in a portion of a definition list item +:::: + +### Tables + +The recommended placement in tables varies based on what part(s) of the table related to the `applies_to` label. + +#### If the badge is relevant to the entire row, add the badge to the end of the first column [table-row] + +Add the badge to the end of the first column to indicate that it applies to all cells in a row. + +For example, the [Streaming Input](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-streaming#_metrics_14) page includes a table that contains one setting per row and a new setting is added in 9.0.4. + +::::{image} ./images/table-entire-row-correct.png +:screenshot: +:alt: +:::: + +In some cases it might be appropriate to add column dedicated to applicability, +but you should avoid adding specific Markdown real estate to the page layout and +causing existing tables with content from long before the base version, +for example Elastic Stack 9.0.0, look incomplete. + +In the same example as above, creating a column dedicated to applicability would +likely take up unnecessary space and could cause confusion since the majority of +rows include content that has been available long before 9.0.0. + +::::{image} ./images/table-entire-row-incorrect.png +:screenshot: +:alt: +:::: + +#### If the badge is relevant to one cell, add the badge to the cell it applies to [table-cell] + +Add the badge to the end of the content in a cell to indicate that it applies to that one cell only. + +For example, the [Collect application data](https://www.elastic.co/docs/solutions/observability/apm/collect-application-data#_capabilities) page includes a table that compares functionality across two methods for collecting APM data, and only one of the methods is in technical preview. + +::::{image} ./images/table-one-cell-correct.png +:screenshot: +:alt: +:::: +::: + +:::{tip} +If the one cell that the badge applies to is in the first column, consider formatting the content +using something other than a table (for example, a definition list) to avoid confusion with the +[previous scenario](#table-row) in which adding the badge to the first column indicates that the +badge applies to the whole row. +::: + +#### If the badge is relevant to part of a cell, follow the appropriate placement guidelines for the elements used in the cell [table-cell-part] + +For example, the [Parse AWS VPC Flow Log](https://www.elastic.co/docs/reference/beats/filebeat/processor-parse-aws-vpc-flow-log) page includes new information relevant to 9.2.0 and later about a setting that already existed before 9.2.0. In this example, the `applies_to` badges should be at the beginning of each list item as described in [the guidelines for lists](#ordered-and-unordered-lists). + +::::{image} ./images/table-part-of-cell-correct.png +:screenshot: +:alt: +:::: +::: + +% Reference: https://github.com/elastic/kibana/pull/229485/files#r2231856744 +:::{tip} +If needed, break the contents of the cell into multiple lines using `
` to isolate the content you're labeling or consider not using a table to format the related content. +::: + +### Tabs + +When you need to show versions as tab titles, consider using [applies-switch](https://elastic.github.io/docs-builder/syntax/applies-switch) instead. The applies-switch component has built-in support for using applies-to metadata as tab titles and render these as badges. + +### Admonitions + +Admonitions support the `applies_to` property to indicate which products or versions the information applies to. Refer to the [admonitions documentation](https://elastic.github.io/docs-builder/syntax/admonitions#applies-to-information) for syntax details. + +### Dropdowns + +Dropdowns support the `applies_to` property to add a badge to the dropdown title. Refer to the [dropdowns documentation](https://elastic.github.io/docs-builder/syntax/dropdowns#with-applies_to-badge) for syntax details. + +### Code blocks + +To specify `applies_to` information for a code block, refer to [](example-scenarios.md#code-block). + +### Images + +To specify `applies_to` information for an image, refer to [](example-scenarios.md#screenshot). diff --git a/contribute-docs/how-to/cumulative-docs/example-scenarios.md b/contribute-docs/how-to/cumulative-docs/example-scenarios.md new file mode 100644 index 0000000000..7a1c47a9d8 --- /dev/null +++ b/contribute-docs/how-to/cumulative-docs/example-scenarios.md @@ -0,0 +1,592 @@ +--- +navigation_title: Example scenarios +--- + +# Cumulative docs 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. +::: + +Browse common scenarios you might run into as a docs contributor that require different approaches to labeling cumulative docs. + +:::{note} +Screenshots might not exactly match the example pages linked to. +::: + +## Content applies to both stateful and serverless [stateful-serverless] + +If an entire page is primarily about using or interacting with both Elastic Stack components and +the Serverless UI, add both the `stack` and `serverless` keys to the `applies_to` in the frontmatter. + +### If released in Serverless, but not yet released in Elastic Stack + +:::{include} /contribute-docs/_snippets/stack-serverless-lifecycle-example.md +::: + + +## Section applicability differs from page-level applicability [page-section-varies] + +When a section has different applicability than the applicability indicated at the +page level in the frontmatter, use section-level `applies_to` badges. + +### If labeling serverless vs. stateful [page-section-varies-product] + + + + +When a documentation set or page is primarily about using a product following its own +versioning schema or some combination of Elastic Stack components and the Serverless UI, +it usually includes content that is meant to be used together (i.e. not parallel sections +like in [If labeling deployment modes](#page-section-varies-deployment)), but is only +available in specific versions or either serverless or stateful. + +% Contributor experience +In this case, docs contributors should include the following at the page level: + +* `stack` with the lowest version that applies to any content (unless it is lower + than the base version, {{version.stack.base}}, in which case omit the version number altogether). +* `serverless` if applicable. + +Then if a section contains content that applies to a different context than what is +defined at the page level, include section-level `applies_to` only with the items +that are different than the page-level `applies_to`. + +% Reader experience +The reader should assume that content in a section with a section-level `applies_to` +is applicable to all the contexts included in the page-level `applies_to` unless +explicitly stated. + +:::{tip} +**Don’t overload with badges that restate the page-level applicability.** +In content that is primarily about serverless vs. stateful, use `unavailable` +if functionality is not available at all in `serverless` or `stack`. +Do not use `unavailable` for specific `stack` versions. +Instead, include the lifecycle and version and the fact that it is not applicable +to other versions will be implied. +::: + +% Example +For example, if a whole page is generally applicable to Elastic Stack 9.0.0 and to Serverless, but one specific section isn’t applicable to Serverless. The content on the [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) page is generally applicable to both Serverless and stateful, but one section only applies stateful: + +* In the frontmatter, specify that the content on the page applies to both unless otherwise specified. +* In a section-level annotation, specify that the content is `unavailable` in `serverless`. + +:::::{tab-set} +::::{tab-item} Image +:::{image} ./images/page-section-varies-product.png +:screenshot: +:alt: +::: +:::: +::::{tab-item} Code +```` +--- +applies_to: + stack: ga + serverless: ga +--- + +# Spaces + +[...] + +## Configure a space-level landing page [space-landing-page] + +```{applies_to} +serverless: unavailable +``` + +[...] +```` +:::: +::::: + +:::{tip} +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: `` {applies_to}`serverless: unavailable` ``. +::: + +### If labeling deployment modes [page-section-varies-deployment] + + + + +When a documentation set or page is primarily about orchestrating, deploying, +or configuring an installation, it usually includes parallel content about multiple +deployment modes (the reader picks one of several sections that is applicable to them). + +% Contributor experience +In this case, docs contributors include all the deployment types that are mentioned +throughout the page in the frontmatter `applies_to`, and in each section they include +only the applicable deployment modes using section-level `applies_to`. + +% Reader experience +The reader should assume that content in a section with a section-level `applies_to` is +not applicable to any deployment modes that are omitted. + +:::{tip} +**Don’t overload with exclusions unless it is necessary.** +In content that is primarily about deployment modes, we do not include `unavailable` badges +for anything in `applies_to` > `deployment`. +::: + +% Example +For example, the content on the [Security](https://www.elastic.co/docs/deploy-manage/security) page is generally applicable to all deployment types, but the first section only applies to Elastic Cloud Hosted and Serverless: + +* In the frontmatter, specify that the content on the page applies to all deployment types unless otherwise specified. +* In a section-level annotation, specify that the content only applies to `ech` and `serverless`. + +:::::{tab-set} +::::{tab-item} Image +:::{image} ./images/page-section-varies-deployment.png +:screenshot: +:alt: +::: +:::: +::::{tab-item} Code +```` +--- +applies_to: + deployment: all +--- + +# Security + +[...] + +## Managed security in Elastic Cloud + +```{applies_to} +deployment: + ech: ga +serverless: ga +``` + +[...] +```` +:::: +::::: + +:::{tip} +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: `` {applies_to}`ech: ga` {applies_to}`serverless: ga` ``. +::: + +## Functionality is added to an unversioned product [unversioned-added] + +When functionality is _first added_ to an unversioned product/deployment mode, +how it is labeled depends on if the functionality is in technical preview, beta, or GA. + +### If the section lifecycle is the same as the page level [unversioned-added-same] + +For example, on the [Project settings](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/project-settings#obs-serverless-project-features) page we added content about the Observability Logs Essentials feature tier, that was added to Serverless in GA. +Since the page's frontmatter already includes `serverless: ga`, there is no need to label the added content. + +However, if the functionality is also applicable to a specific version of a versioned product/deployment mode, +label the content with both versioned and unversioned applicability information. + +For example, on the [Lens](https://www.elastic.co/docs/explore-analyze/visualize/lens) page we added information +about a new option that was added to Serverless in GA and the Elastic Stack in GA in 9.1.0. +Even though it is added to Serverless, an unversioned product, in the same lifecycle state as the page-level annotation, +we still include an inline annotation to make it clear that this is not only available in the Elastic Stack. + +:::::{tab-set} +::::{tab-item} Image +:::{image} ./images/example-unversioned-added-same-exception.png +:screenshot: +:alt: +::: +:::: +::::{tab-item} Code +``` +--- +applies_to: + stack: ga + serverless: ga +--- + +# Lens [lens] + +[...] + +#### Tables + +**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**. +``` +:::: +::::: + +### If the section lifecycle is different than the page level [unversioned-added-different] + +For example, on the [Dashboard controls](https://www.elastic.co/docs/explore-analyze/dashboards/add-controls#add-esql-control) page we added content about new ES|QL controls functionality that was added to Serverless in preview. +Since this is different than the page-level applicability in the frontmatter, `serverless: ga`, +label the content about the new functionality with `serverless: preview`. + +:::::{tab-set} +::::{tab-item} Image +:::{image} ./images/example-unversioned-added-different.png +:screenshot: +:alt: +::: +:::: +::::{tab-item} Code +```` +--- +serverless: ga +--- + +# Add filter controls + +[...] + +## Add ES|QL controls + +```{applies_to} +serverless: preview +``` + +[...] +```` +:::: +::::: + +## Functionality changes lifecycle state [lifecycle-changed] + +When the functionality described in any content changes lifecycle state, +how it is labeled varies by whether the product/deployment mode is versioned or unversioned. + +For example, the majority of the content on the [Lens](https://www.elastic.co/docs/explore-analyze/visualize/lens) +page was applicable to both Elastic Stack and to Serverless. +One specific section describes functionality that was in technical preview in Elastic Stack 9.0.0 and +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. + +:::::{tab-set} +::::{tab-item} Image +:::{image} ./images/example-lifecycle-changed.png +:screenshot: +:alt: +::: +:::: +::::{tab-item} Code +```` +--- +applies_to: + stack: ga + serverless: ga +--- + +# Lens [lens] + +[...] + +### Assign colors to terms [assign-colors-to-terms] + +```{applies_to} +stack: ga 9.1, preview 9.0, +serverless: ga +``` + +[...] + +```` +:::: +::::: + + +## Functionality is removed [removed] + +When the functionality described in any level of content is removed, +how to handle it varies by which lifecycle it was in before being removed and +whether the product/deployment mode is versioned or unversioned. + +### If a GA or deprecated feature is removed from a versioned product + +For example, we removed the `securitySolution:enableVisualizationsInFlyout` setting that was described on the +[Configure advanced settings](https://www.elastic.co/docs/solutions/security/get-started/configure-advanced-settings) +page from the Elastic Stack in 9.1.0 and from Serverless around the same time. +Since this this functionality is still available before 9.1.0, we need that content to continue to be +available to users on Elastic Stack earlier versions while communicating to users on newer versions +that it is no longer available. + +:::::{tab-set} +::::{tab-item} Image +:::{image} ./images/example-removed-unversioned-exception.png +:screenshot: +:alt: +::: +:::: +::::{tab-item} Code +```` +--- +applies_to: + stack: all + serverless: + security: all +--- + +# Configure advanced settings [security-advanced-settings] + +[...] + +## Access the event analyzer and Session View from the event or alert details flyout [visualizations-in-flyout] + +```{applies_to} +stack: removed 9.1 +serverless: removed +``` + +[...] +```` +:::: +::::: + +### If a beta or technical preview feature is removed [beta-removed] + +If the functionality was only ever available in beta or technical preview before being removed, +you can remove the content altogether regardless of whether it is versioned or unversioned. + +### If a feature is removed from an unversioned product + +If the functionality was only ever available in an unversioned product or deployment mode, +remove the content altogether. + +## Code block content varies [code-block] + +Often the content in a code block will vary between situations (versions, deployment types, etc). +There are a couple possible solutions. + +### Solution A: Use a code callout [code-block-callout] + +Using a code callout is the lightest-touch solution, but might not be sufficient in all cases. + +**When to use a code callout**: + +* The code block and its callouts fit vertically on a typical laptop screen. + This will reduce the risk of users copying the code snippet without reading the information in the callout. +* Syntax is either just added or just removed — syntax is not modified. + It is difficult to communicate that some syntax is needed in more than one situation but varies depending on the situation. +* The code block will not require more than 3 `applies_to`-related callouts. + At that point, the code becomes more difficult to read and use. + +**Best practices**: + +* Place the badge at the beginning of the callout. + +**Example**: On the [Entity Analytics](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-entity-analytics#_configuration_3) page, we added a new option to a code block that was only made available in 9.1.0. + +::::{image} ./images/example-code-block-callout.png +:screenshot: +:::: + +### Solution B: Use 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. + +**Best practices**: + +* Try to minimize the number of tabs where possible, + but do not mix tabs and `applies_to`-related code callouts. +* Try not to include information surrounding a code block in the tabs. + Make the tab content as small as possible apart from the procedure itself. + +**Example**: 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). + +::::{image} ./images/example-code-block-tabs.png +:screenshot: +:::: + +## Workflows vary [workflow] + +When one or more steps in a process differs. + +### Solution A: Use inline `applies_to` [workflow-inline] + +Using inline `applies_to` badges to a few line items in an ordered list is the lightest-touch solution, +but might not be sufficient in all cases. + +**When to use inline `applies_to`**: + +* Workflow steps that vary between situations can be easily isolated. +* Each step that varies, only varies between 3 or fewer situations (deployment types, versions, etc). +* There are no more than 3 steps that need to be split into multiple lines with `applies_to` badges. + +**Best practices**: + +* Follow the [best practices for ordered and unordered lists](badge-placement.md#ordered-and-unordered-lists) + including the order of items and the placement of labels. + +**Example**: Only one item in an ordered list varies between Serverless and stateful. + +::::{image} ./images/workflow-inline.png +:screenshot: +:::: + +### Solution B: Use tabs [workflow-tabs] + +:::{include} _snippets/applies-switch-and-tabs.md +::: + +Tabs are minimally disruptive in many situations. + +**When to use tabs**: + +* Using [inline `applies_to` badges](#workflow-inline) isn't appropriate. +* All the tabs fit horizontally on a single row on a typical laptop screen. + This is usually around a maximum of four tabs. +* The tab with the most content fits vertically on a typical laptop screen. + This is usually around of 20 lines. + +**Best practices**: + +* Try to minimize the number of tabs where possible. Try to work around small differences by + rewording or adding context in prose or in `note` style admonitions. +* Try not to include information surrounding a procedure in the tabs. + Make the tab content as small as possible apart from the procedure itself. +* Consider breaking up procedures into sets of procedures if only one section differs between contexts. + +**Example**: 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. + +::::{image} ./images/example-workflow-tabs.png +:screenshot: +:::: + +### Solution C: Use sibling pages [workflow-sibling-pages] + +Sibling pages are a last resort when no other solutions are appropriate. + +**When to use sibling pages**: + +* Neither [inline `applies_to` badges](#workflow-inline) or [tabs](#workflow-tabs) are appropriate. +* The workflow has significant differences across multiple procedures. +* There are chained procedures where not all of the procedures are needed for all contexts + or where the flow across procedures is muddied when versioning context is added. +* The workflow exists in a very complex page that is already heavily using tabs and other tools we use for versioning differences. + This makes it difficult to add another “layer” of content. +* Product lifecycle state changes like when technical preview or beta transitions to GA. + +**Best practices**: + +* Use consistent structure and terminology across sibling pages. +* Use redirects when one version becomes the primary approach. + +**Example**: We use separate pages for ECH and Serverless billing information: + +* [Cloud Hosted deployment billing dimensions](https://elastic.co/docs/deploy-manage/cloud-organization/billing/cloud-hosted-deployment-billing-dimensions) +* [{{serverless-short}} project billing dimensions](https://elastic.co/docs/deploy-manage/cloud-organization/billing/serverless-project-billing-dimensions) + +## Screenshots vary [screenshot] + +Sometimes the UI differs between versions, deployment types or other conditions. + +### Solution A: Use tabs [screenshot-tabs] + +:::{include} _snippets/applies-switch-and-tabs.md +::: + +**When to use 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. + +**Best practices**: +* Keep any explanatory text outside the tab unless it's specific to the screenshot inside. + +**Example**: As of the Elastic Stack 9.1.0 release, there are no examples of this approach being used in live docs +except for with images used in workflows. + +### Solution B: Add a note [screenshot-note] + +In cases where only a small visual detail differs (for example, a button label or icon), it’s often more efficient to add a note rather than creating tabbed screenshots. + +**When to use a note**: +* When the screenshot is mostly consistent, but includes minor visual or behavioral differences. +* When adding another screenshot would be redundant or distracting. + +**Best practices**: +* Keep notes concise, ideally one sentence. +* Place the note directly after the screenshot. +* Use an `applies_to` badge at the start of the note if relevant. + +**Example**: As of the Elastic Stack 9.1.0 release, there are no examples of this approach being used in live docs +except for with images used in workflows. + +### Solution C: Keep the screenshot aligned with the latest version [screenshot-latest] + +In cases where the screenshot is rather conceptually demonstrating a capability, it's fine not to version it. + +For example, versioning the screenshot on the [Dashboards](https://www.elastic.co/docs/explore-analyze/dashboards) parent page would not add tremendous value unless the capability drastically evolves. + +## Multiple adjacent block elements vary [multiple-block] + +### Solution A: Use tabs [multiple-block-tabs] + +:::{include} _snippets/applies-switch-and-tabs.md +::: + +**When to use 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. + +**Best practices**: +* Only include content that varies inside the tab — don’t wrap entire pages or unrelated information. +* Keep tabs short and focused to reduce cognitive load. +* Label tabs clearly and consistently (e.g., by version or product). + +% TO DO: Add example +% **Example**: +% + +### Solution B: Use headings [multiple-block-headings] + +_Work in progress._ + +% TO DO: Add all sections +% **When to use headings**: +% **Best practices**: +% **Example**: + +## 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. In that case, use two `applies_to` badges so that users can see clearly the versions in which the functionality is introduced. Order the `applies_to` badges starting with the latest version, and ending with the earliest version. (Automatic ordering for multiple badges is not currently supported.) + +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. + +:::::{tab-set} +::::{tab-item} Image +:::{image} ./images/example-multiple-patch.png +:screenshot: +:alt: +::: +:::: +::::{tab-item} Code +```markdown +* `terminate`: exits the template without falling back to the default value + and without causing an error. It takes a single string argument that is + logged in debug logging. {applies_to}`stack: ga 9.1.2` {applies_to}`stack: ga 9.0.6` +``` +:::: +::::: diff --git a/contribute-docs/how-to/cumulative-docs/guidelines.md b/contribute-docs/how-to/cumulative-docs/guidelines.md new file mode 100644 index 0000000000..c9340dc8ed --- /dev/null +++ b/contribute-docs/how-to/cumulative-docs/guidelines.md @@ -0,0 +1,304 @@ +--- +navigation_title: Guidelines +--- + +# Cumulative docs 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. +::: + +Start by asking yourself: + +* Does this content vary between products, versions, or deployment types? +* Is this a feature lifecycle change or just content improvement? +* Will users benefit from knowing this information? + +If the answer to at least one of these questions is _yes_, follow these guidelines to write cumulative documentation. + +## What `applies_to` tags can communicate + +### Type + +In cumulative documentation, you can use `applies_to` to communicate: + +* **Product- or deployment-specific availability**: When content applies to or functions differently between products or deployment types (for example, Elastic Cloud Serverless or Elastic Cloud Hosted). Read more in [Product and deployment model applicability](#products-and-deployment-models). +* **Feature lifecycle and version-related functionality**: When features are introduced, modified, or removed in specific versions, including lifecycle changes (for example, going from Beta to GA). Read more in [Version and product lifecycle applicability](#versions). + +Both types of applicability are added as part of the same `applies_to` tagging logic. +The product or deployment type is the [key](reference.md#key) +and the [feature lifecycle](reference.md#lifecycle) +and [version](reference.md#version) make up the value. + +``` +: +``` + +### Level + +For each type of applicability information, you can add `applies_to` metadata at different levels: + +* **Page-level** metadata is **mandatory** and must be included in the frontmatter. + 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 ... +* **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. + +For a full syntax reference for page, section, and inline level `applies_to` annotations, +refer to [the applies_to syntax guide](https://elastic.github.io/docs-builder/syntax/applies). + +## General guidelines + +### When to tag content + +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: + +* **Functionality is added**: + Tag content if the functionality described is added in a specific release. + +* **Functionality changes state**: + Tag content if existing functionality changes state (`preview`, `beta`, `ga`, `deprecated`, `removed`). + +* **Availability varies**: + Tag content if the availability of the functionality described differs across products or deployment types. + +### When _not_ to tag content + +You generally do not need to tag: + +* **Content-only changes**: + Do _not_ tag content-only changes like typo fixes, formatting updates, information architecture updates, + or other documentation updates that don't reflect feature lifecycle changes. + +* **Every paragraph/section**: + You do _not_ need to tag every section or paragraph. + Only tag when the context or applicability changes from what has been established earlier on the page. + +* **Unversioned products**: + For products where all users are always on the latest version (like serverless), + you do _not_ need to tag workflow changes if the product lifecycle is unchanged. + +### 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. +* **Don’t assume features are available everywhere**: + For example, if a Kibana UI panel is missing from Serverless, + notate it in the documentation even if it is intuitive. +* **Clarify version availability per context**: + 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. + 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 + +### 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. + +For example: + +{applies_to}`stack: preview 9.0.5, beta 9.1, ga 9.2` + +### 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. + +:::{important} +Key ordering only occurs if all keys are declared in the same directive. Keys declared seperately, for example: ``` {applies_to}`stack: ga` {applies_to}`serverless: preview` ```, will not be reordered by docs-builder. +::: + +Keys are ordered as follows: + +1. **Stack/Serverless**: Stack, Serverless +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: + +```{applies_to} +deployment: + ece: ga + self: ga +stack: ga +serverless: ga +``` + +## Product and deployment model applicability [products-and-deployment-models] + +For the full list of supported product and deployment model tags, +refer to [](reference.md#key). + +### Guidelines [products-and-deployment-models-guidelines] + +* **Always include page-level product and deployment model applicability information**. + This is _mandatory_ for all pages. +* **Determine if section or inline applicability information is necessary.** + This _depends on the situation_. + * For example, if a portion of a page is applicable to a different context than what was specified at the page level, + clarify in what context it applies using section or inline `applies_to` badges. +% Source: https://elastic.github.io/docs-builder/versions/#defaults-and-hierarchy +* **Do not assume a default product or deployment type.** + Treat all products and deployment types equally. Don't treat one as the "base" and the other as the "exception". + +### Common scenarios [products-and-deployment-models-examples] + +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 a product following its own versioning schema. + % TO DO: Add example + % ([example](example-scenarios.md#)) +* A whole page is generally applicable to Elastic Stack 9.0 and to Serverless, + but one specific section isn’t applicable to Serverless. + ([example](example-scenarios.md#page-section-varies-product)) +* The whole page is generally applicable to all deployment types, + but one specific paragraph only applies to Elastic Cloud Hosted and Serverless, + and another paragraph only applies to Elastic Cloud Enterprise. + ([example](example-scenarios.md#page-section-varies-deployment)) +* 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. + % TO DO: Add example + % ([example](example-scenarios.md#)) + +## Version and product lifecycle applicability [versions] + +### Guidelines [versions-guidelines] + +* **Ensure your change is related to a specific version.** + Even though a change is made when a specific version is the latest version, + it does not mean the added or updated content only applies to that version. + * For example, you should not use version tagging when fixing typos, + improving styling, or adding a long-forgotten setting. +% Source: https://github.com/elastic/kibana/pull/229485/files#r2231876006 +* **Do _not_ use version numbers in prose**. + Avoid using version numbers in prose adjacent to `applies_to` badge to prevent + confusion when the badge is rendered with `Planned` ahead of a release. +* **Cumulative documentation is not meant to replace release notes.** + * For example, 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, it does need a release note entry to document the change. +* **Consider carefully when the change is going to be published.** + Read more about how publishing can vary between repos in the [branching strategy guide](https://elastic.github.io/docs-builder/contribute/branching-strategy/). +* **Do not use date-based tagging for unversioned products.** + `applies_to` does not accept date-based versioning. +* **Be aware of exceptions.** + 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. + +### Common scenarios [versions-examples] + +#### Unversioned products + +For unversioned products like {{serverless-short}} or {{ecloud}}: + +* When a new feature is introduced in an unversioned product: + * If it is added in GA, label only at the page level. + There is no need to label newly added GA content in unversioned products at the section or line level + if it is already labeled as available at the page level. + ([example](example-scenarios.md#unversioned-added)) + * If it is added in technical preview or beta, and the related content is added to an existing page + that is already labeled as generally available in the unversioned product at the page level, + label the new technical preview or beta content at the section or line level. + ([example](example-scenarios.md#unversioned-added)) +* When a feature in an unversioned product changes lifecycle state to `preview`, `beta`, `ga` or `deprecated`, + replace the previous lifecycle state with the new lifecycle state. + ([example](example-scenarios.md#lifecycle-changed)) +* When a feature in an unversioned product is removed, remove the content altogether + unless the content also applies to another context that is versioned + (refer to [Mixed versioned and unversioned products](#mixed)). + +#### Versioned products + +For versioned products like the Elastic Stack: + +* When a new feature is introduced in a versioned product, label the content with the lifecycle state + and the version in which it was introduced. + % TO DO: Add example + % ([example](example-scenarios.md#)) +* When a feature in a versioned product changes lifecycle state, + append the new lifecycle state and the version in which the state changed to the relevant key in `applies_to`. + This applies to all lifecycle states including `preview`, `beta`, `ga`, `deprecated`, and `removed` + ([example](example-scenarios.md#lifecycle-changed)). + + +#### Mixed versioned and unversioned products [mixed] + +* 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), + then it must be kept for any user reading the page that may be using a version of + the product prior to the removal. + ([example](example-scenarios.md#removed)) + +## When to indicate something is NOT applicable + +By default, we communicate that content does not apply to a certain context by simply **not specifying it**. +For example, a page describing how to create an {{ech}} deployment just requires identifying "{{ech}}" as context. No need to overload the context with additional `serverless: unavailable` indicators. + +This is true for most situations. However, it can still be useful to call it out in a few specific scenarios: + +* When there is a high risk of confusion for users. This may be subjective, but let’s imagine a scenario where a feature is available in 2 out of 3 serverless project types. It may make sense to clarify and be explicit about the feature being “unavailable” for the 3rd type. For example: + + ```yml + --- + applies_to: + stack: ga + serverless: + elasticsearch: ga + security: ga + observability: unavailable + --- + ``` + + +* When a specific section, paragraph or list item has specific applicability that differs from the context set at the page or section level, and the action is not possible at all for that context (meaning that there is no alternative). For example: + + ````md + --- + applies_to: + stack: ga + serverless: ga + —-- + + # Spaces + + [...] + + ## Configure a space-level landing page [space-landing-page] + ```{applies_to} + serverless: unavailable + ``` + ```` + diff --git a/contribute-docs/how-to/cumulative-docs/images/admonition-correct.png b/contribute-docs/how-to/cumulative-docs/images/admonition-correct.png new file mode 100644 index 0000000000..1201495017 Binary files /dev/null and b/contribute-docs/how-to/cumulative-docs/images/admonition-correct.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/definition-list-entire-item.png b/contribute-docs/how-to/cumulative-docs/images/definition-list-entire-item.png new file mode 100644 index 0000000000..c834684d45 Binary files /dev/null and b/contribute-docs/how-to/cumulative-docs/images/definition-list-entire-item.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/definition-list-item-incorrect.png b/contribute-docs/how-to/cumulative-docs/images/definition-list-item-incorrect.png new file mode 100644 index 0000000000..05914dc9f0 Binary files /dev/null and b/contribute-docs/how-to/cumulative-docs/images/definition-list-item-incorrect.png differ 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 new file mode 100644 index 0000000000..ae0d270173 Binary files /dev/null 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 new file mode 100644 index 0000000000..45baa8fb83 Binary files /dev/null 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 new file mode 100644 index 0000000000..935bd23e8e Binary files /dev/null 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 new file mode 100644 index 0000000000..5dfcf339cd Binary files /dev/null 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 new file mode 100644 index 0000000000..369f555cde Binary files /dev/null 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 new file mode 100644 index 0000000000..3013b09bbf Binary files /dev/null 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-different.png b/contribute-docs/how-to/cumulative-docs/images/example-unversioned-added-different.png new file mode 100644 index 0000000000..69a771631e Binary files /dev/null and b/contribute-docs/how-to/cumulative-docs/images/example-unversioned-added-different.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 new file mode 100644 index 0000000000..0c8b0dfcbc Binary files /dev/null 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 new file mode 100644 index 0000000000..05aa314a30 Binary files /dev/null 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 new file mode 100644 index 0000000000..3dcb5eb765 Binary files /dev/null and b/contribute-docs/how-to/cumulative-docs/images/heading-correct.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/heading-incorrect.png b/contribute-docs/how-to/cumulative-docs/images/heading-incorrect.png new file mode 100644 index 0000000000..673d0246b7 Binary files /dev/null and b/contribute-docs/how-to/cumulative-docs/images/heading-incorrect.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 new file mode 100644 index 0000000000..2483fd0c02 Binary files /dev/null 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 new file mode 100644 index 0000000000..e6da7a477f Binary files /dev/null and b/contribute-docs/how-to/cumulative-docs/images/list-misc-correct.png 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 new file mode 100644 index 0000000000..a7e7a2d0a7 Binary files /dev/null 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 new file mode 100644 index 0000000000..14a01089be Binary files /dev/null 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 new file mode 100644 index 0000000000..4e44279be4 Binary files /dev/null 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 new file mode 100644 index 0000000000..3cc9796527 Binary files /dev/null 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-entire-row-incorrect.png b/contribute-docs/how-to/cumulative-docs/images/table-entire-row-incorrect.png new file mode 100644 index 0000000000..86a6411f99 Binary files /dev/null and b/contribute-docs/how-to/cumulative-docs/images/table-entire-row-incorrect.png differ diff --git a/contribute-docs/how-to/cumulative-docs/images/table-one-cell-correct.png b/contribute-docs/how-to/cumulative-docs/images/table-one-cell-correct.png new file mode 100644 index 0000000000..d56dead8fb Binary files /dev/null and b/contribute-docs/how-to/cumulative-docs/images/table-one-cell-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 new file mode 100644 index 0000000000..15c4448375 Binary files /dev/null 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 new file mode 100644 index 0000000000..53f23f676a Binary files /dev/null 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 new file mode 100644 index 0000000000..446baad3d8 --- /dev/null +++ b/contribute-docs/how-to/cumulative-docs/index.md @@ -0,0 +1,84 @@ +# Write cumulative documentation + +:::{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. +::: + +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. + +:::{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. +::: + +## 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. + +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. + +:::{image} ./images/reader-experience.png +:screenshot: +:alt: +::: + +## 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. + +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 removals: 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. + +To achieve this, the Markdown source files integrate a tagging system. + +### When to tag content + +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: + +* Functionality is added +* 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).** + +### When _not_ to tag content + +You generally do not need to tag: + +* Content-only changes, like fixing typos +* Every paragraph/section when the applicability has been established earlier on the page +* Unversioned products, where all users are always on the latest version, + when adding features that are generally available + +### How dynamic tags work [how-do-these-tags-behave-in-the-output] + +We have a central version config called [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml), which tracks the latest released versions of our products. It also tracks the earliest version of each product documented in the Docs V3 system (the earliest available on elastic.co/docs). + +This central version config is used in certain inline version variables and drives our dynamic rendering logic, which allows us to label documentation related to unreleased versions as `planned`, continuously release documentation, and document our Serverless and {{stack}} offerings in one place. + +:::{tip} +Read more about how site configuration works in the [docs-builder configuration guide](https://elastic.github.io/docs-builder/configure/site/). +::: + +:::{include} /contribute-docs/_snippets/tag-processing.md +::: + +### How to tag content + +Read more about _how_ to tag content in: + +* [Guidelines](guidelines.md): + Review more detailed guidance on when to tag content. +* [Badge usage and placement](badge-placement.md): + Learn how to integrate `applies_to` badges into docs content. +* [Example scenarios](example-scenarios.md): + Browse common scenarios you might run into as a docs contributor that require different approaches to labeling cumulative docs. +* [`applies_to` syntax guide](https://elastic.github.io/docs-builder/syntax/applies): + Reference all valid values and syntax patterns available in `applies_to`. diff --git a/contribute-docs/how-to/cumulative-docs/reference.md b/contribute-docs/how-to/cumulative-docs/reference.md new file mode 100644 index 0000000000..b199205237 --- /dev/null +++ b/contribute-docs/how-to/cumulative-docs/reference.md @@ -0,0 +1,30 @@ +# Quick reference + +:::{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. +::: + +The `applies_to` directive uses the following format: + +``` +: +``` + +This page provides minimal reference information on the `applies_to` directive. For more detailed information, refer to [the applies_to syntax guide](https://elastic.github.io/docs-builder/syntax/applies). + +## key + +:::{include} /contribute-docs/_snippets/applies_to-key.md +::: + +## lifecycle + +:::{include} /contribute-docs/_snippets/applies_to-lifecycle.md +::: + +## version + +:::{include} /contribute-docs/_snippets/applies_to-version.md +::: diff --git a/contribute-docs/how-to/index.md b/contribute-docs/how-to/index.md new file mode 100644 index 0000000000..31c1cf9090 --- /dev/null +++ b/contribute-docs/how-to/index.md @@ -0,0 +1,19 @@ +# How-to guides + +Find practical guides for common documentation tasks. + +## Write cumulative documentation + +:::{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. +::: + +Learn about the cumulative documentation model and how to tag content for different versions and deployments. + +- [Write cumulative documentation](cumulative-docs/index.md) - Overview and when to tag content +- [Guidelines](cumulative-docs/guidelines.md) - Detailed tagging guidance +- [Badge placement](cumulative-docs/badge-placement.md) - Where to place applies_to tags +- [Example scenarios](cumulative-docs/example-scenarios.md) - Common contribution scenarios +- [Reference](cumulative-docs/reference.md) - Complete applies_to syntax reference diff --git a/contribute-docs/images/bear.png b/contribute-docs/images/bear.png new file mode 100644 index 0000000000..117c9465a4 Binary files /dev/null and b/contribute-docs/images/bear.png differ diff --git a/contribute-docs/images/edit-this-page.png b/contribute-docs/images/edit-this-page.png new file mode 100644 index 0000000000..1148ff5b89 Binary files /dev/null and b/contribute-docs/images/edit-this-page.png differ diff --git a/contribute-docs/images/elastic-docs-vscode.gif b/contribute-docs/images/elastic-docs-vscode.gif new file mode 100644 index 0000000000..20f3c241ac Binary files /dev/null and b/contribute-docs/images/elastic-docs-vscode.gif differ diff --git a/contribute-docs/images/headings.png b/contribute-docs/images/headings.png new file mode 100644 index 0000000000..2e07aba99d Binary files /dev/null and b/contribute-docs/images/headings.png differ diff --git a/contribute-docs/images/nav-title.png b/contribute-docs/images/nav-title.png new file mode 100644 index 0000000000..d97c4abc22 Binary files /dev/null and b/contribute-docs/images/nav-title.png differ diff --git a/contribute-docs/index.md b/contribute-docs/index.md index 14fa8bef71..b13a87fc7b 100644 --- a/contribute-docs/index.md +++ b/contribute-docs/index.md @@ -4,19 +4,43 @@ navigation_title: Contribute to the docs # Contribute to Elastic documentation -Find the relevant pages for contributing to the official Elastic documentation. +In April 2025, Elastic migrated to a new documentation system at [elastic.co/docs](https://www.elastic.co/docs), using Markdown and the [`docs-builder`](https://elastic.github.io/docs-builder/) toolchain, which coincided with the release of {{stack}} 9.0.0, {{ece}} 4.0.0, and {{eck}} 3.0.0. -## Contribute to current docs +This documentation site includes docs for: +- {{stack}} 9.x +- {{ece}} 4.x +- {{eck}} 3.x +- {{ech}} +- {{serverless-full}} -We have two distinct systems for contributing to the current Elastic docs: +Refer to [versioning and availability](/get-started/versioning-availability.md) to learn more. + +This documentation is [**cumulative**](how-to/cumulative-docs/index.md): a new set of docs is not published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes. + +:::{tip} +To learn more about the new docs UX, read [how to use the documentation](/get-started/howto-use-the-docs.md). +::: + +## Contribute to `elastic.co/docs` (Markdown) |System|What it covers|Published at|Format|How to contribute |----|----|----|----|----|----| -|Main docs|Guides, Troubleshooting, release notes, etc.|[elastic.co/docs](https://www.elastic.co/docs)|Markdown+|- [Contribution guide](https://elastic.github.io/docs-builder/contribute/)

- [Syntax guide](https://elastic.github.io/docs-builder/syntax/)| -|API references|Elastic REST APIs|[elastic.co/docs/api](https://www.elastic.co/docs/api/)|[OpenAPI](https://swagger.io/specification/)|[Contribute to API docs](./api-docs/index.md)| +|Main docs|Guides, troubleshooting, release notes, etc.|[elastic.co/docs](https://www.elastic.co/docs)|Markdown|- [On the web](on-the-web.md) (quick edits)
- [Locally](locally.md) (complex changes)
- [Syntax guide](syntax-quick-reference.md)| +|API references|Elastic REST APIs|[elastic.co/docs/api](https://www.elastic.co/docs/api/)|[OpenAPI](https://swagger.io/specification/)|[Contribute to API docs](api-docs/index.md)| -## Contribute to legacy docs +## Report issues or request features + +|Issue type|Where to report| +|----|----| +|Documentation|- [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) or [fix it yourself](locally.md)
- Elastic employees can use the [internal repo](https://github.com/elastic/docs-content-internal/issues/new/choose)| +|`docs-builder`|- [Bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml)
- [Discussion](https://github.com/elastic/docs-builder/discussions)| + +## Contribute to `elastic.co/guide` (Asciidoc) |System|What it covers|Published at|Format/toolchain|How to contribute |----|----|----|----|----|----| -|Legacy docs|Elastic docs & API references for 8.x and earlier|[elastic.co/guide](https://www.elastic.co/guide/index.html)|Asciidoc|[Contribute to legacy docs](https://elastic.github.io/docs-builder/contribute/#contribute-to-elastic.coguide)| +|`elastic.co/guide` (Asciidoc)|Elastic docs & API references for 8.x and earlier|[elastic.co/guide](https://www.elastic.co/guide/index.html)|Asciidoc|[Contribute to the Asciidoc docs](./asciidoc-guide.md)| + +:::{note} +If you need to update documentation in both the MarkDown and Asciidoc systems, you'll need two separate PRs. Refer to [Updating docs in both systems](asciidoc-guide.md#updating-docs-in-both-systems). +::: diff --git a/contribute-docs/locally.md b/contribute-docs/locally.md new file mode 100644 index 0000000000..589f890093 --- /dev/null +++ b/contribute-docs/locally.md @@ -0,0 +1,175 @@ +# Contribute locally + +This document describes the process to set up Elastic documentation repositories locally, enabling you to contribute effectively. + +## Prerequisites [#prerequisites] + +To write and push updates to Elastic documentation, you need the following: + +* **A code editor**: We recommend [Visual Studio Code](https://code.visualstudio.com/download). See [Documentation tools](tools.md) for helpful extensions. +* **Git installed on your machine**: To install Git, see [How to install Git](https://github.com/git-guides/install-git) +* **A GitHub account**: Sign up for an account on [Github](https://github.com/) + +## Install `docs-builder` [#install-docs-builder] + +There are two different ways to install and run `docs-builder`: + +1. Download, extract, and run the binary (recommended). +1. Clone the repository and build the binary from source. + +This guide follows the first option. If you'd like to clone the repository and build from source, learn how in the [project readme](https://github.com/elastic/docs-builder?tab=readme-ov-file#docs-builder). + +:::::{tab-set} + +::::{tab-item} macOS & Linux + +1. **Download and run the install script** + + Run this command to download and install the latest version of `docs-builder`: + + ```sh + curl -sL https://ela.st/docs-builder-install | sh + ``` + + This downloads the latest binary to `/usr/local/bin`, makes it an executable, and installs it to your user PATH. This means you can use the `docs-builder` command from any location of your machine to deploy and run documentation repositories like `docs-builder`, `docs-content` and so on. + + You can optionally specify a specific version to install: + + ```sh + DOCS_BUILDER_VERSION=0.40.0 curl -sL https://ela.st/docs-builder-install | sh + ``` + +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](http://localhost:3000): + + ```sh + docs-builder serve + ``` + + The path to the `docset.yml` file that you want to build can be specified with `-p`. + + :::{important} + Run `docs-builder` without `serve` to run a full build and detect errors. + ::: + +To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub. + +If you get a `Permission denied` error, make sure that you aren't trying to run a directory instead of a file. Also, grant the binary file execution permissions using `chmod +x docs-builder`. + +:::: + +::::{tab-item} Windows + +1. **Download and run the install script** + + Run this command to download and install the latest version of `docs-builder`: + + ```powershell + iex (New-Object System.Net.WebClient).DownloadString('https://ela.st/docs-builder-install-win') + ``` + + This downloads the latest binary, makes it executable, and installs it to your user PATH. + You can optionally specify a specific version to install: + + ```powershell + $env:DOCS_BUILDER_VERSION = '0.40.0'; iwr -useb https://ela.st/docs-builder-install.ps1 | iex + ``` + + To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub. + +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](http://localhost:3000): + + ```sh + docs-builder serve + ``` + The path to the `docset.yml` file that you want to build can be specified with `-p`. +:::: +::::: + + +## Clone a content repository [#clone-content] + +:::{tip} +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 the location of the source file. +::: + +Clone the [`docs-content`](https://github.com/elastic/docs-content) repository to a directory of your choice. The `docs-content` repository is the home for most narrative documentation at Elastic. + +```sh +git clone https://github.com/elastic/docs-content.git +``` + +## Write the docs [#write-docs] + +We write docs in Markdown. Refer to our [syntax quick reference](syntax-quick-reference.md) for the flavor of Markdown we support and all of our custom directives that enable you to add a little extra pizzazz to your docs. + +This documentation is **cumulative**. This means that a new set of docs is not published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content. [Learn how to write cumulative documentation](how-to/cumulative-docs/index.md). + +:::{include} _snippets-contribute/tagged-warning.md +::: + +## Build the docs + +Before pushing your changes, verify them locally by running: + +``` +docs-builder +``` + +The build process informs you of any critical errors or warnings. It also shows less critical issues as Hints. Make sure you don't introduce any new build errors, warnings, or hints. + +## Push your changes [#push-changes] + +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) + +## Preview locally [#local-docs-preview] + +`docs-builder` can serve docs locally. This means you can edit the source and see the result in the browser in real time. + +To serve the local copy of the documentation in your browser, follow these steps: + +::::::{stepper} + +:::::{step} Change directory to a docs repository + +For example, `docs-content`: + +```sh +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](http://localhost:3000). If necessary, specify the path to the `docset.yml` file that you want to build with `-p`. + +For example: + +::::{tab-set} + +:::{tab-item} macOS & Linux + +```sh +docs-builder serve +``` +::: + +:::{tab-item} Windows + +```powershell +docs-builder serve -p .\docs-content +``` +::: +:::: +::::: + +:::::{step} Open docs in the browser +To view the documentation locally, navigate to [http://localhost:3000](http://localhost:3000). +::::: +:::::: diff --git a/contribute-docs/on-the-web.md b/contribute-docs/on-the-web.md new file mode 100644 index 0000000000..70a84ee737 --- /dev/null +++ b/contribute-docs/on-the-web.md @@ -0,0 +1,38 @@ +# Contribute on the web + +Learn how to make documentation updates directly in your browser without setting up a local development environment. + +:::{tip} +If you're working in [GitHub Codespaces](https://github.com/features/codespaces) or [github.dev](https://github.dev), you can install the [VS Code extension](tools.md#vs-code-extension) to simplify the authoring experience. +::: + +## Suggesting quick edits + +For content hosted on [elastic.co/docs](https://www.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. + +To make quick edits to a single page: + +1. Navigate to the documentation page that needs updates. +2. Click the **Edit this page** button. This opens the file in GitHub's editor. + + :::{image} images/edit-this-page.png + :width: 200px + :alt: Edit this page button + ::: +3. Make your changes in the editor. +4. Click **Commit changes**. +5. Write a clear, verb-focused commit message describing your changes. +6. Select **Propose changes**. This takes you to the pull request creation page where you can edit the description if necessary. +7. Select **Create pull request** to submit your changes. + +An Elastician will review, merge, and propagate your change to the right places for publication. + +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 +::: + +## Editing `elastic.co/guide` docs (Asciidoc) + +If you need to contribute to [elastic.co/guide](https://elastic.co/guide) pages, refer to [Contribute to `elastic.co/guide` (Asciidoc)](asciidoc-guide.md) to learn about the Asciidoc system. + diff --git a/contribute-docs/syntax-quick-reference.md b/contribute-docs/syntax-quick-reference.md new file mode 100644 index 0000000000..18ad532d33 --- /dev/null +++ b/contribute-docs/syntax-quick-reference.md @@ -0,0 +1,688 @@ +--- +navigation_title: "Syntax quick reference" +--- + +# Syntax quick reference + +Elastic documentation uses a custom implementation of [MyST Markdown](https://mystmd.org/) with extended syntax for directives, metadata, and tagging. + +This page offers quick guidance on commonly used syntax elements. Elements are in alphabetical order. + +For the full syntax reference, go to [elastic.github.io/docs-builder/syntax/](https://elastic.github.io/docs-builder/syntax/). + + +:::{tip} +Contributing to `elastic.co/guide`? Refer to [Contribute to `elastic.co/guide` (Asciidoc)](asciidoc-guide.md). +::: + +## Admonitions + +Use admonitions to caution users, or to provide helpful tips or extra information. + +::::{dropdown} Types + +These examples show the syntax first, followed by the rendered admonition. + + **Warning** + + ```markdown + :::{warning} + Users could permanently lose data or leak sensitive information. + ::: + ``` + :::{warning} + Users could permanently lose data or leak sensitive information. + ::: + + **Important** + + ```markdown + :::{important} + Less dire than a warning. Users might encounter issues with performance or stability. + ::: + ``` + :::{important} + Less dire than a warning. Users might encounter issues with performance or stability. + ::: + + **Note** + ```markdown + :::{note} + Supplemental information that provides context or clarification. + ::: + ``` + :::{note} + Supplemental information that provides context or clarification. + ::: + + **Tip** + ```markdown + :::{tip} + Advice that helps users work more efficiently or make better choices. + ::: + ``` + :::{tip} + Advice that helps users work more efficiently or make better choices. + ::: + + **Custom** + ```markdown + :::{admonition} Special note + Custom admonition with custom label. + ::: + ``` + :::{admonition} Special note + Custom admonition with custom label. + ::: + +:::: + +**DOs**
+✅ **Do:** Use custom admonitions as needed + +**DON'Ts**
+❌ **Don't:** Stack admonitions
+❌ **Don't:** Overload a page with too many admonitions + +[More details: Admonitions →](https://elastic.github.io/docs-builder/syntax/admonitions) +
+
+ +--- + +## Anchors + +A default anchor is automatically created for each [heading](#headings), in the form `#heading-text` (hyphenated, lowercase, special characters and spaces trimmed). To create a custom anchor, add it in square brackets at the end of a heading: `[my-better-anchor]` + +:::{dropdown} Default anchor +```markdown +#### Hello world! + +``` +::: + + +:::{dropdown} Custom anchor +```markdown +#### Hello world! [get-started] +``` +::: + +**DOs**
+✅ **Do:** Create custom anchors for repeated structural headings like "Example request"
+ +**DON'Ts**
+❌ **Don't:** Include punctuation marks in custom anchors
+❌ **Don't:** Define custom anchors in text that is not a heading + +[More details: Links →](https://elastic.github.io/docs-builder/syntax/links#same-page-links-anchors) +
+
+ +--- + +## Applies to + +Use applies_to metadata to tag content for specific contexts, for example whether a feature is available on certain products, versions, or deployment types. + +This metadata enables you to write [cumulative documentation](how-to/cumulative-docs/index.md), because Elastic no longer publishes separate docs sets for every minor release. + +**Example: Section tag** + +:::{dropdown} Syntax +````markdown +# Stack-only content +```{applies_to} +stack: +``` +```` +::: + +:::{dropdown} Output +#### Stack-only content +```{applies_to} +stack: +``` +::: + +For full syntax and more examples, refer to [the `applies_to` documentation](https://elastic.github.io/docs-builder/syntax/applies). + +:::{tip} +The syntax for `applies_to` metadata differs depending on whether it's added at the [page level](https://elastic.github.io/docs-builder/syntax/applies/#page-level) (in frontmatter), [section level](https://elastic.github.io/docs-builder/syntax/applies/#section-level) (after a heading), or [inline](https://elastic.github.io/docs-builder/syntax/applies/#inline-level). +::: + + + +% TODO restore details when guidance has settled + +**DOs**
+✅ **Do:** Define a set of [page-level tags](https://elastic.github.io/docs-builder/syntax/applies#page-level) in a front matter block
+✅ **Do:** Add section-level tags in an `{applies_to}` [directive](https://elastic.github.io/docs-builder/syntax/applies#section-level) after a heading
+✅ **Do:** Indicate versions (`major.minor` with an optional `[.patch]`) and release phases like `beta` + +**DON'Ts**
+❌ **Don't:** Include `applies_to` tags in admonitions
+❌ **Don't:** Add `applies_to` tags to general, broadly applicable content
+
+
+ +--- + +## Code blocks + +Multi-line blocks for code, commands, configuration, and similar content. Use three backticks ` ``` ` on separate lines to start and end the block. For syntax highlighting, add a language identifier after the opening backticks. + +:::{dropdown} Syntax +```markdown + ```yaml + server.host: "0.0.0.0" + elasticsearch.hosts: ["http://localhost:9200"] + ``` +``` +::: + +:::{dropdown} Output +```yaml +server.host: "0.0.0.0" +elasticsearch.hosts: ["http://localhost:9200"] +``` +::: + + +**DOs**
+✅ **Do:** Include code blocks within lists or other block elements as needed
+✅ **Do:** Add language identifiers like `yaml`, `json`, `bash` + +**DON'Ts**
+❌ **Don't:** Place code blocks in admonitions
+❌ **Don't:** Use inline code formatting (single backticks) for multi-line content + +[More details: Code →](https://elastic.github.io/docs-builder/syntax/code) +
+
+ +--- + +## Code callouts + +Inline annotations that highlight or explain specific lines in a code block. + +### Explicit callout +To explicitly create a code callout, add a number marker in angle brackets (`<1>`, `<2>`, ...) at the end of a line. Add the corresponding callout text below the code block, in a numbered list that matches the markers. + +:::{dropdown} Syntax + + ````markdown callouts=false + ```json + { + "match": { + "message": "search text" <1> + } + } + ``` + 1. Searches the `message` field for the phrase "search text" + ```` +::: + +:::{dropdown} Output + +```json +{ + "match": { + "message": "search text" <1> + } +} +``` +1. Searches the `message` field for the phrase "search text"
+::: + +### Magic (comment-based) callout [magic-callout] +Add comments with `//` or `#` to magically create callouts. + +:::{dropdown} Syntax + ````markdown callouts=false + ```json + { + "match": { + "message": "search text" // Searches the message field + } + } + ``` + ```` +::: + +:::{dropdown} Output + +```json +{ + "match": { + "message": "search text" // Searches the message field + } +} +``` +::: + +**DOs**
+✅ **Do:** Keep callout text short and specific
+✅ **Do:** Use only one type of callout per code block (don't mix [explicit](#explicit-callout) and [magic](#magic-callout))
+✅ **Do:** Make sure there's a corresponding list item for each explicit callout marker in a code block + +**DON'Ts**
+❌ **Don't:** Overuse callouts — they can impede readability + +[More details: Code callouts→](https://elastic.github.io/docs-builder/syntax/code#code-callouts) +
+
+ +--- + +## Comments + +Use `%` to add single-line comments. Use HTML-style `` for multi-line comments. + +:::{dropdown} Syntax +```markdown + % This is a comment + This is regular text + + + Regular text after multi-line comment +``` +::: + +:::{dropdown} Output +% This is a comment +This is regular text + + +Regular text after multi-line comment + +::: + +**DOs**
+✅ **Do:** Add a space after the `%` in single-line comments + +**DON'Ts**
+❌ **Don't:** Use `#` or `//` for comments (reserved for [magic callouts](#magic-callout)) +
+
+ +--- + +## Dropdowns + +Collapsible blocks for hiding and showing content. + +::::{dropdown} Syntax +```markdown + :::{dropdown} Title or label + Collapsible content + ::: +``` +:::: + +::::{dropdown} Output +:::{dropdown} Title or label +Collapsible content +::: +:::: + +**DOs**
+✅ **Do:** Use dropdowns for text, lists, images, code blocks, and tables
+✅ **Do:** Add `:open:` to auto-expand a dropdown by default + +**DON'Ts**
+❌ **Don't:** Use dropdowns for very long paragraphs or entire sections + +[More details: Dropdowns →](https://elastic.github.io/docs-builder/syntax/dropdowns) +
+
+ +--- + +## Headings +Title of a page or a section. To create a heading, add number signs `#` at the beginning of the line (one `#` for each heading level). + +:::{dropdown} Syntax +```markdown +# Heading 1 +## Heading 2 +### Heading 3 +#### Heading 4 +``` +::: + +::::{dropdown} Output +:::{image} images/headings.png +:screenshot: +:alt: Heading levels +:width: 300px +::: + +:::: + +**DOs**
+✅ **Do:** Start every page with a Heading 1
+✅ **Do:** Use only one Heading 1 per page
+✅ **Do:** Define custom anchors for repeated headings + +**DON'Ts**
+❌ **Don't:** Use headings in tabs or dropdowns
+❌ **Don't:** Go deeper than Heading 4 + +[More details: Headings →](https://elastic.github.io/docs-builder/syntax/headings) +
+
+ +--- + +## Images +Standard Markdown images: `[alt text]` in square brackets, followed by the image path in parentheses. + +:::{dropdown} Syntax +```markdown +![Bear emerging from hibernation](images/bear.png) +``` +::: + +:::{dropdown} Output +![Bear emerging from hibernation](images/bear.png) +::: + +**DOs**
+✅ **Do:** Store images in a centralized directory
+✅ **Do:** Follow v3 [best practices for screenshots](how-to/cumulative-docs/badge-placement.md#images)
+✅ **Do:** Specify `:screenshot:` in an [image directive](https://elastic.github.io/docs-builder/syntax/images#screenshots) to add a border + +**DON'Ts**
+❌ **Don't:** Use lots of UI screenshots that create a maintenance burden
+❌ **Don't:** Include confidential info or PII in an image
+❌ **Don't:** Add a drop shadow or torn edge effect + +[More details: Images →](https://elastic.github.io/docs-builder/syntax/images) +
+
+ +--- + + +## Inline formatting +Elastic Docs v3 supports standard Markdown inline formatting. + +`_emphasis_`     _italics_
+`**strong**`    **bold**
+\` `monospace` \`     `inline code` (single backticks)
+`~~strikethrough~~`     ~~strikethrough~~
+`\* escaped`     \* escaped character + +**DOs**
+✅ **Do:** Use `_emphasis_` to introduce a term
+✅ **Do:** Use inline `code` in headings and other elements as needed + +**DON'Ts**
+❌ **Don't:** Overuse `**strong**` or `_emphasis_` — aim for readability +
+
+ +--- + +## Links + +Standard Markdown links to doc pages, sections (anchors), or external content. Prefer absolute paths for links within the doc set. + +:::{dropdown} Syntax +```markdown + [link text](/absolute/file.md#anchor) + [link text](https://external-site.com) + [link text](other-repo://path/file.md) + (#same-page-anchor) +``` +::: + +**DOs**
+✅ **Do:** Use inline formatting in link text: `[**bold link**](https://elastic.github.io/docs-builder/syntax/bold-page)`
+✅ **Do:** Autogenerate link text from the page or section title: `[](https://elastic.github.io/docs-builder/syntax/use-title#section)`
+✅ **Do:** Define a custom [anchor](#anchors) by adding `[anchor-text]` at the end of a heading line + +**DON'Ts**
+❌ **Don't:** Use unclear, inaccessible link text like "click here" or "this"
+❌ **Don't:** Include terminal punctuation in link text + +[More details: Links →](https://elastic.github.io/docs-builder/syntax/links) +
+
+ +--- + +## Lists + +Standard Markdown ordered (numbered) and unordered (bulleted) lists. Indent with four spaces to nest paragraphs and other elements under a list item. Unordered lists can start with hyphens `-`, asterisks `*`, or plus signs `+`. + +:::{dropdown} Syntax + + ``` + - Unordered item 1 + ····Paragraph within item 1 + - Unordered item 2 + ``` + + ``` + 1. Ordered item 1 + 2. Ordered item 2 + ``` +::: + +**DOs**
+✅ **Do:** Add code blocks, images, admonitions, and other content within a list item
+✅ **Do:** Nest lists, mixing ordered and unordered as needed
+✅ **Do:** Use parallel structure and phrasing in list items
+✅ **Do:** Capitalize only the first word of list items (sentence case)
+✅ **Do:** Use terminal punctuation consistently and only for complete sentences + +**DON'Ts**
+❌ **Don't:** Use lists solely for layout purposes
+❌ **Don't:** Use lists for structured data or comparisons — use tables instead + +[More details: Lists →](https://elastic.github.io/docs-builder/syntax/lists) +
+
+ +--- + +## Navigation title + +Optional [front matter](https://elastic.github.io/docs-builder/syntax/frontmatter) element that sets a custom title for docs navigation features: appears in the left nav (table of contents), breadcrumbs, and previous/next links. Compare [headings](#headings) (H1 = page title). + +:::{dropdown} Syntax + +Page front matter (yaml): + +```yaml + --- + navigation_title: "Minimalist identifier" + --- +``` + +Page title (Markdown H1): + +```markdown + # Full descriptive page title with product context +``` + +::: + +:::{dropdown} Output + +![Rendered nav title](images/nav-title.png) + +::: + + +**DOs**
+✅ **Do:** Use active phrasing and shorter forms
+✅ **Do:** Make sure the navigation title clearly identifies the page topic
+✅ **Do:** Omit product names that appear in the full H1 page title + +**DON'Ts**
+❌ **Don't:** Duplicate the H1 page title
+❌ **Don't:** Use a long navigation title or lots of punctuation
+❌ **Don't:** Abbreviate with periods or ellipses + +[More details: Title →](https://elastic.github.io/docs-builder/syntax/titles) +
+
+ +--- + +## Substitutions +Key-value pairs that define reusable variables. They help ensure consistency and enable short forms. To use a substitution (or "sub"), surround the key with curly brackets: `{{variable}}`
+ +% TODO: link to our global docset.yml? + +### Define a sub + +:::{dropdown} Syntax + +In `docset.yml`: + +``` +subs: + ccs: "cross-cluster search" + ech: "Elastic Cloud Hosted" + kib: "Kibana" +``` +::: + + +### Use a sub + +This example uses the sub defined in `docset.yml` above. + +:::{dropdown} Syntax + +In `myfile.md`: + +``` +{{ech}} supports most standard {{kib}} settings. +``` +::: + +:::{dropdown} Output +% TODO replace with actual subs once _docset.yml is updated + +Elastic Cloud Hosted supports most standard Kibana settings. +::: + +**DOs**
+✅ **Do:** Check the global `docset.yml` file for existing product and feature name subs
+✅ **Do:** Use substitutions in code blocks by setting `subs=true`
+✅ **Do:** Define new page-specific substitutions as needed + +**DON'Ts**
+❌ **Don't:** Override a `docset.yml` sub by defining a page-level sub with the same key (causes build errors)
+❌ **Don't:** Use substitutions for common words that don't need to be standardized + +[More details: Substitutions →](https://elastic.github.io/docs-builder/syntax/substitutions) +
+
+ +--- + +## Tabs + +Block element that displays content in switchable tabs to help users zero in on the right context (such as a deployment or language). [Synced tab groups](https://elastic.github.io/docs-builder/syntax/tabs#tab-groups) are supported. + +:::::{dropdown} Syntax +```markdown + ::::{tab-set} + + :::{tab-item} Tab 1 title + Tab 1 content + ::: + + :::{tab-item} Tab 2 title + Tab 2 content + ::: + + :::: +``` +::::: + +:::::{dropdown} Output +::::{tab-set} + +:::{tab-item} Tab 1 title +Tab 1 content +::: + +:::{tab-item} Tab 2 title +Tab 2 content +::: + +:::: +::::: + +**DOs**
+✅ **Do:** Use clear, descriptive tab labels
+✅ **Do:** Make sure all tabs have the same type of content and similar goals
+✅ **Do:** Keep tab content scannable and self-contained (don't make users switch tabs to follow steps or compare content)
+✅ **Do:** Include other block elements in tabs, like [admonitions](#admonitions) + +**DON'Ts**
+❌ **Don't:** Nest tabs
+❌ **Don't:** Split step-by-step procedures across tabs
+❌ **Don't:** Use more than 6 tabs (use as few as possible)
+❌ **Don't:** Use tabs in [dropdowns](#dropdowns) + + +[More details: Tabs →](https://elastic.github.io/docs-builder/syntax/tabs) +
+
+ +--- + +## Tables + +Standard table layout for structured data. Automatically scrolls horizontally if needed. The **header** row is optional. + +:::{dropdown} Syntax +```markdown + | Header | Header | + | ------ | ------ | + | Data | Info | + | Info | Data | +``` +::: + +:::{dropdown} Output +| Header | Header | +| ------ | ------ | +| Data | Info | +| Info | Data | +::: + +**DOs**
+✅ **Do:** Use leading and trailing pipes for clarity
+✅ **Do:** Add spaces for readability (they're trimmed)
+✅ **Do:** Keep cell content scannable and parallel
+✅ **Do:** Use standard Markdown text alignment when necessary (`:-- --: :--:`) + +**DON'Ts**
+❌ **Don't:** Insert block elements or multiple paragraphs in a table cell
+❌ **Don't:** Use a table solely for position or spacing purposes + +[More details: Tables →](https://elastic.github.io/docs-builder/syntax/tables) diff --git a/contribute-docs/toc.yml b/contribute-docs/toc.yml index ce69a6f7af..cf7ee263f9 100644 --- a/contribute-docs/toc.yml +++ b/contribute-docs/toc.yml @@ -1,5 +1,19 @@ toc: - file: index.md + - file: on-the-web.md + - file: locally.md + - file: syntax-quick-reference.md + - folder: how-to + children: + - file: index.md + - folder: cumulative-docs + children: + - file: index.md + - file: guidelines.md + - file: badge-placement.md + - file: example-scenarios.md + - file: reference.md + - file: tools.md - folder: api-docs children: - file: index.md @@ -12,4 +26,5 @@ toc: - file: elasticsearch-api-docs-quickstart.md - file: kibana-api-docs-quickstart.md - file: workflows.md - - file: help.md \ No newline at end of file + - file: help.md + - file: asciidoc-guide.md \ No newline at end of file diff --git a/contribute-docs/tools.md b/contribute-docs/tools.md new file mode 100644 index 0000000000..c548240123 --- /dev/null +++ b/contribute-docs/tools.md @@ -0,0 +1,36 @@ +--- +navigation_title: Tools +--- + +# Documentation tools + +These tools help you write documentation more efficiently, reduce context-switching, and catch errors before you commit. + +## VS Code extension + +The [Elastic Docs Utilities extension](https://marketplace.visualstudio.com/items?itemName=Elastic.elastic-docs-v3-utilities) simplifies authoring with autocompletion, catches syntax errors with real-time validation, and enables you to preview variables inline. + +:::{image} images/elastic-docs-vscode.gif +:screenshot: +:alt: Elastic Docs VS Code extension demo +:width: 800px +::: + +### Availability + +The extension is available in VS Code whether you're: + +- Working [locally](locally.md) in the VS Code desktop application +- Working [in the browser](on-the-web.md) in VS Code web editors ([GitHub Codespaces](https://github.com/features/codespaces), [github.dev](https://github.dev)) + +### Key capabilities + +- Autocompletion for directives, frontmatter, and inline roles +- Real-time validation of syntax and structure +- Variable previews and substitution support + +### Installation + +You can install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Elastic.elastic-docs-v3-utilities). + +% TODO: Add Vale and LLM sections when ready. \ No newline at end of file