diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 5ca89b4bb..7b58307e7 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,131 +1,211 @@ ---- -applies_to: - stack: ga 9.1 - deployment: - eck: ga 9.0 - ess: beta 9.1 - ece: discontinued 9.2.0 - self: unavailable 9.3.0 - serverless: - security: ga 9.0.0 - elasticsearch: beta 9.1.0 - observability: discontinued 9.2.0 - product: planned 9.5, discontinued 9.7 ---- - # Applies to -Allows you to annotate a page or section's applicability. +The `applies_to` metadata allows you to specify which product versions, deployment types, and environments a specific page, section, or line applies to. Documentation published using Elastic Docs V3 follows a [cumulative model](../contribute/index.md) where a single page covers multiple versions cumulatively over time, instead of creating separate pages for each minor release. -### Syntax +## Syntax ``` [version], [version] ``` -Taking a mandatory [life-cycle](#life-cycle) with an optional version. +Taking a mandatory [life-cycle](#life-cycle) with an optional [version](#version). + +### Life cycle + +`applies_to` accepts the following lifecycle states: -#### Life cycle: * `preview` * `beta` - * `development` * `deprecated` - * `planned` - * `discontinued` + * `removed` * `unavailable` * `ga` -#### Version +Both versioned and unversioned products use the same lifecycle tags, but only versioned products can be marked `ga`. Unversioned products are considered `ga` by default and don’t need specification. + +### Version Can be in either `major.minor` or `major.minor.patch` format -#### Examples +Versioned products require a `version` tag to be used with the `lifecycle` tag. See [Syntax](#syntax): ``` -planned 9.5, discontinued 9.7 -discontinued 9.2.0 -all +applies_to: + stack: preview 9.1, ga 9.4 + deployment: + ece: deprecated 9.2, removed 9.8 ``` +Unversioned products use `lifecycle` tags without a version: -`all` means generally available for all active versions - -```yaml +``` applies_to: - serverless: all + serverless: + elasticsearch: beta + observability: removed ``` -`all` can also be specified at a version level +## When and where to use `applies_to` -```yaml -applies_to: - stack: beta all - serverless: beta -``` +✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments. -Note `all` just means we won't be rendering the version portion in the HTML. +❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes. +The `applies_to` metadata can be added at different levels in the documentation: -## Structured model +* [Page-level](#page-annotations) metadata is **mandatory** and must be included in the frontmatter. This defines the overall applicability of the page across products, deployments, and environments. +* [Section-level](#section-annotations) annotations allow you to specify different applicability for individual sections when only part of a page varies between products or versions. +* [Inline](#inline-annotations) annotations allow fine-grained annotations within paragraphs or definition lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. -![Applies To Model](images/applies.png) +### Lifecycle examples -The above model is projected to the following structured yaml. +#### Unversioned products +Unversioned products aren’t following a fixed versioning scheme and are released a lot more often than versioned products. All users are using the same version of this product. +* When a change is released in `ga`, it **doesn’t need any specific tagging**. +* When a change is introduced as preview or beta, use `preview` or `beta` as value for the corresponding key within the `applies_to`: -```yaml ---- -applies_to: - stack: - deployment: - eck: - ess: - ece: - self: - serverless: - security: - elasticsearch: - observability: - product: ---- -``` -This allows you to annotate various facets as defined in [](../migration/versioning.md) + ``` + --- + applies_to: + serverless: preview + --- + ``` +* When a change introduces a deprecation, use deprecated as value for the corresponding key within the applies_to: -## Page annotations + ``` + --- + applies_to: + deployment: + ess: deprecated + --- + ``` -Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status +* When a change removes a feature, remove the content. +**Exception:** If the content also applies to another context (for example a feature is removed in both Kibana 9.x and Serverless), then it must be kept for any user reading the page that may be using a version of Kibana prior to the removal. For example: + ``` + --- + applies_to: + stack: deprecated 9.1, removed 9.4 + serverless: removed + --- + ``` -```yaml +#### Versioned products + +* When a change is released in `ga`, users need to know which version the feature became available in: + + ``` + --- + applies_to: + stack: ga 9.3 + --- + ``` + +* When a change is introduced as preview or beta, use `preview` or `beta` as value for the corresponding key within the `applies_to`: + + ``` + --- + applies_to: + stack: beta 9.1 + --- + ``` + +* When a change introduces a deprecation, use `deprecated` as value for the corresponding key within the `applies_to`: + + ``` + --- + applies_to: + deployment: + ece: deprecated 4.2 + --- + ``` + +* When a change removes a feature, any user reading the page that may be using a version of Kibana prior to the removal must be aware that the feature is still available to them. For that reason, we do not remove the content, and instead mark the feature as removed: + + ``` + --- + applies_to: + stack: deprecated 9.1, removed 9.4 + --- + ``` + +#### Identify multiple states for the same content + +A feature is deprecated in ECE 4.0 and is removed in 4.8. At the same time, it has already been removed in Elastic Cloud Hosted: + +``` --- applies_to: - stack: ga 9.1 deployment: - eck: ga 9.0 - ess: beta 9.1 - ece: discontinued 9.2.0 - self: unavailable 9.3.0 - serverless: - security: ga 9.0.0 - elasticsearch: beta 9.1.0 - observability: discontinued 9.2.0 - product: planned 9.5, discontinued 9.7 + ece: deprecated 4.0, removed 4.8 + ess: removed --- ``` - -## Section annotation [#sections] +### Page annotations + +All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use yaml frontmatter to indicate each deployment targets availability and lifecycle status. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). + +#### Page annotation examples + +There are 3 typical scenarios to start from: +1. The documentation set or page is primarily about using or interacting with Elastic Stack components or the Serverless UI: + + ```yaml + --- + applies_to: + stack: ga + serverless: ga + products: + -id: kibana + -id: elasticsearch + -id: elastic-stack + --- + ``` + +2. The documentation set or page is primarily about orchestrating, deploying or configuring an installation (only include relevant keys): + + ```yaml + --- + applies_to: + serverless: ga + deployment: + ess: ga + ece: ga + eck: ga + products: + -id: cloud-serverless + -id: cloud-hosted + -id: cloud-enterprise + -id: cloud-kubernetes + --- + ``` + +3. The documentation set or page is primarily about a product following its own versioning schema: + + ```yaml + --- + applies_to: + product: ga + products: + -id: edot-collector + --- + ``` + +### Section annotations ```yaml {applies_to} stack: ga 9.1 deployment: eck: ga 9.0 ess: beta 9.1 - ece: discontinued 9.2.0 - self: unavailable 9.3.0 + ece: deprecated 9.2.0 + self: unavailable serverless: - security: ga 9.0.0 - elasticsearch: beta 9.1.0 - observability: discontinued 9.2.0 -product: planned 9.5, discontinued 9.7 + security: unavailable + elasticsearch: beta + observability: deprecated +product: preview 9.5, deprecated 9.7 ``` A header may be followed by an `{applies_to}` directive which will contextualize the applicability @@ -152,9 +232,60 @@ stack: ga 9.1 ``` ```` -This will allow the yaml inside the `{applies-to}` directive to be fully highlighted. +This will allow the yaml inside the `{applies_to}` directive to be fully highlighted. + +#### Section annotation examples -## Inline Applies To +1. The whole page is generally applicable to Elastic Stack 9.0 and to Serverless, but one specific section isn’t applicable to Serverless (and there is no alternative for it): + + ````markdown + ## Configure a space-level landing page [space-landing-page] + ```{applies_to} + stack: ga + serverless: unavailable + ``` + ```` + +2. The whole page is generally applicable to Elastic Cloud Enterprise and Elastic Cloud Hosted, but one specific paragraph only applies to Elastic Cloud Enterprise, and another paragraph explains the same, but for Elastic Cloud Hosted: + + ````markdown + ## Secure a deployment [secure-deployment-ech] + ```{applies_to} + deployment: + ess: ga + ``` + + [...] + + ## Secure a deployment [secure-deployment-ece] + ```{applies_to} + deployment: + ece: ga + ``` + + [...] + ```` +3. A specific section, paragraph or list item has specific applicability that differs from the context set at the page or section level, and the action is not possible at all for that context (meaning that there is no alternative). For example: + + ````markdown + --- + applies_to: + stack: ga + serverless: ga + --- + + # Spaces + + [...] + + ## Configure a space-level landing page [space-landing-page] + ```{applies_to} + stack: ga + serverless: unavailable + ``` + ```` + +### Inline annotations Inline applies to can be placed anywhere using the following syntax @@ -164,14 +295,16 @@ This can live inline {applies_to}`section: [version]` An inline version example would be {applies_to}`stack: beta 9.1` this allows you to target elements more concretely visually. -A common use case would be to place them on definition lists: +#### Inline annotation examples -Fruit {applies_to}`stack: preview 9.1` -: A sweet and fleshy product of a tree or other plant that contains seed and can be eaten as food. Common examples include apples, oranges, and bananas. Most fruits are rich in vitamins, minerals and fiber. +1. The whole page is generally applicable to Elastic Stack 9.0 and to Serverless, but one specific section isn’t applicable to Serverless (and there is no alternative): -Applies {preview}`9.1` -: A sweet and fleshy product of a tree or other plant that contains seed and can be eaten as food. Common examples include apples, oranges, and bananas. Most fruits are rich in vitamins, minerals and fiber. + ````markdown + **Spaces** let you organize your content and users according to your needs. + - Each space has its own saved objects. + - {applies_to}`stack: ga` {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. + ```` A specialized `{preview}` role exist to quickly mark something as a technical preview. It takes a required version number as argument. @@ -181,44 +314,26 @@ Property {preview}`` : definition body ``` +## Structured model +![Applies To Model](images/applies.png) -## Examples - -#### Stack only -```yaml {applies_to} -stack: ga 9.1 -``` - - -#### Stack with deployment -```yaml {applies_to} -stack: ga 9.1 -deployment: - eck: ga 9.0 - ess: beta 9.1 -``` - -#### Deployment only -```yaml {applies_to} -deployment: - ece: discontinued 9.2.0 - self: unavailable 9.3.0 -``` - -#### Serverless only -```yaml {applies_to} -serverless: ga 9.0.0 -``` +The above model is projected to the following structured yaml. -#### Serverless with project differences -```yaml {applies_to} -serverless: - security: ga 9.0.0 - elasticsearch: beta 9.1.0 - observability: discontinued 9.2.0 -``` -#### Stack with product -```yaml {applies_to} -stack: ga 9.1 +```yaml +--- +applies_to: + stack: + deployment: + eck: + ess: + ece: + self: + serverless: + security: + elasticsearch: + observability: + product: +--- ``` +This allows you to annotate various facets as defined in [](../migration/versioning.md) \ No newline at end of file diff --git a/docs/syntax/quick-ref.md b/docs/syntax/quick-ref.md index c7d280db7..445c719ae 100644 --- a/docs/syntax/quick-ref.md +++ b/docs/syntax/quick-ref.md @@ -146,7 +146,7 @@ The `applies_to` tags are scope signals for readers, not comprehensive metadata. **DOs**
✅ **Do:** Define a set of [page-level tags](applies.md#page-annotations) in a front matter block
-✅ **Do:** Add section-level tags in an `{applies_to}` [directive](applies.md#sections) after a heading
+✅ **Do:** Add section-level tags in an `{applies_to}` [directive](applies.md#section-annotations) after a heading
✅ **Do:** Indicate versions (`major.minor` with an optional `[.patch]`) and release phases like `beta` **DON'Ts**
diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index a68b931e3..e914bf3d9 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -39,7 +39,7 @@ deployment: self: unavailable 9.3.0 ``` -*see [`applies`](/syntax/applies.md#sections)* +*see [`applies`](/syntax/applies.md#section-annotations)* **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed