diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 61076f1ac..8ee3a794d 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -45,7 +45,7 @@ This [tagging system](#applies-to) is mandatory for all of the public-facing doc Use the [`applies_to`](../syntax/applies.md) tag to indicate which versions, deployment types, or release stages each part of the content is relevant to. -You must always use the `applies_to` tag at the [page](../syntax/applies.md#page-annotations) level. Optionally, you can also use it at the [section](../syntax/applies.md#sections) or [inline](../syntax/applies.md#inline-applies-to) level if certain parts of the content apply only to specific versions, deployment types, or release stages. +You must always use the `applies_to` tag at the [page](../syntax/applies.md#page-annotations) level. Optionally, you can also use it at the [section](../syntax/applies.md#section-annotations) or [inline](../syntax/applies.md#inline-annotations) level if certain parts of the content apply only to specific versions, deployment types, or release stages. ## Report a bug diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 5ca89b4bb..731b0bf26 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,131 +1,227 @@ ---- -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. +Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a [cumulative approach](../contribute/index.md#cumulative-docs): instead of creating separate pages for each product and release, we update a single page with product- and version-specific details over time. + +To support this, source files use a tagging system to indicate: +* Which Elastic products and deployment models the content applies to. +* When a feature changes state relative to the base version. + +This is what the `applies_to` metadata is for. It can be used at the page, section, or inline level to specify applicability with precision. + +## When and where to use `applies_to` + +The `applies_to` metadata can be added at different levels in the documentation: + +* [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. + +### Do’s and don’ts + +✅ Use `applies_to` tags when features change state (`preview`, `beta`, `ga`, `deprecated`, `removed`) or when availability differs across deployments and environments. + +✅ Use `applies_to` tags to indicate which product or deployment type the content applies to. This is mandatory for every page. -### Syntax +✅ Use `applies_to` tags when features change state in a specific update or release. + +❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes. + +❌ You don’t need to tag every section or paragraph. Only do so if the context or applicability changes from what has been established earlier. + +❌ If the product is not versioned (meaning all users are always on the latest version, like in serverless or cloud), you do not need to tag a new GA feature. + +## 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 +### 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 -``` - -`all` means generally available for all active versions - -```yaml applies_to: - serverless: all + stack: preview 9.1, ga 9.4 + deployment: + ece: deprecated 9.2, removed 9.8 ``` +Unversioned products use `lifecycle` tags without a version: -`all` can also be specified at a version level - -```yaml -applies_to: - stack: beta all - serverless: beta ``` - -Note `all` just means we won't be rendering the version portion in the HTML. - - -## Structured model - -![Applies To Model](images/applies.png) - -The above model is projected to the following structured yaml. - -```yaml ---- applies_to: - stack: - deployment: - eck: - ess: - ece: - self: serverless: - security: - elasticsearch: - observability: - product: ---- + elasticsearch: beta + observability: removed ``` -This allows you to annotate various facets as defined in [](../migration/versioning.md) -## Page annotations - -Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status +## Examples +### Lifecycle examples + +#### Unversioned products +Unversioned products don't follow a fixed versioning scheme and are released a lot more often than versioned products. All users are using the same version of this product. +* When a change is released in `ga`, it **doesn’t need any specific tagging**. +* When a change is introduced as preview or beta, use `preview` or `beta` as value for the corresponding key within the `applies_to`: + + ``` + --- + applies_to: + serverless: preview + --- + ``` +* When a change introduces a deprecation, use deprecated as value for the corresponding key within the `applies_to`: + + ``` + --- + applies_to: + deployment: + ess: deprecated + --- + ``` + +* When a change removes a feature, remove the content. +**Exception:** If the content also applies to another context (for example a feature is removed in both Kibana 9.x and Serverless), then it must be kept for any user reading the page that may be using a version of Kibana prior to the removal. For example: + + ``` + --- + applies_to: + stack: deprecated 9.1, removed 9.4 + serverless: removed + --- + ``` + +#### 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: -```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 - 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 @@ -136,7 +232,7 @@ the `{applies_to}` directive **MUST** be preceded by a heading directly. ::: -Note that this directive needs triple backticks since its content is literal. See also [](index.md#literal-directives) +Note that this directive requires triple backticks since its content is literal. See also [](index.md#literal-directives) ````markdown ```{applies_to} @@ -152,9 +248,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. -## Inline Applies To +#### Section annotation examples + +1. The whole page is generally applicable to Elastic Stack 9.0 and to Serverless, but one specific section isn’t applicable to Serverless (and there is no alternative for it): + + ````markdown + ## Configure a space-level landing page [space-landing-page] + ```{applies_to} + stack: ga + serverless: unavailable + ``` + ```` + +2. The whole page is generally applicable to Elastic Cloud Enterprise and Elastic Cloud Hosted, but one specific paragraph only applies to Elastic Cloud Enterprise, and another paragraph explains the same, but for Elastic Cloud Hosted: + + ````markdown + ## Secure a deployment [secure-deployment-ech] + ```{applies_to} + deployment: + ess: ga + ``` + + [...] + + ## Secure a deployment [secure-deployment-ece] + ```{applies_to} + deployment: + ece: ga + ``` + + [...] + ```` +3. A specific section, paragraph or list item has specific applicability that differs from the context set at the page or section level, and the action is not possible at all for that context (meaning that there is no alternative). For example: + + ````markdown + --- + applies_to: + stack: ga + serverless: ga + --- + + # Spaces + + [...] + + ## Configure a space-level landing page [space-landing-page] + ```{applies_to} + stack: ga + serverless: unavailable + ``` + ```` + +### Inline annotations Inline applies to can be placed anywhere using the following syntax @@ -164,14 +311,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 +330,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