diff --git a/contribute-docs/_snippets/dimensions.md b/contribute-docs/_snippets/dimensions.md new file mode 100644 index 0000000000..b61286beaa --- /dev/null +++ b/contribute-docs/_snippets/dimensions.md @@ -0,0 +1,9 @@ +The `applies_to` keys fall into three dimensions: + +| Dimension | Values | +| --- | --- | +| Stack/Serverless | `stack`, `serverless` | +| Deployment | `deployment` (with subkeys: `ece`, `eck`, `ech`, `self`), `serverless` | +| Product | `product` (with subkeys, including those for APM agents, EDOT SDKs, and client libraries) | + +Use only one dimension at the page level. `serverless` can appear in both the Stack/Serverless and Deployment dimensions. diff --git a/contribute-docs/how-to/cumulative-docs/badge-placement.md b/contribute-docs/how-to/cumulative-docs/badge-placement.md index 339a1f79d3..801444ce05 100644 --- a/contribute-docs/how-to/cumulative-docs/badge-placement.md +++ b/contribute-docs/how-to/cumulative-docs/badge-placement.md @@ -39,7 +39,7 @@ There are more specific guidelines on badge placement to follow when using speci ### 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. +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. You should use only one `applies_to` [dimension](/contribute-docs/how-to/cumulative-docs/guidelines.md#dimensions) at the page level. This dimension represent's the user's primary context, whether it's a platform version, deployment type, or supporting piece of software. ::::{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. diff --git a/contribute-docs/how-to/cumulative-docs/example-scenarios.md b/contribute-docs/how-to/cumulative-docs/example-scenarios.md index 86300dc5b7..3bcae065ba 100644 --- a/contribute-docs/how-to/cumulative-docs/example-scenarios.md +++ b/contribute-docs/how-to/cumulative-docs/example-scenarios.md @@ -5,34 +5,38 @@ 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. +While you can use any of these tools at any stage, the tools and approaches you use for cumulative documentation often differ depending on the maturity and complexity of your documentation. The scenarios below are organized by documentation stage to help you find the right approach for your situation. + :::{note} Screenshots might not exactly match the example pages linked to. ::: -## Content applies to both stateful and serverless [stateful-serverless] +## Early stage: New features and basics + +When you're documenting a new feature or writing new guides or procedures, start with page-level tagging and section-level clarifications. + +### 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 +#### 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] +### 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] +#### If labeling serverless vs. stateful [page-section-varies-product]