Write cumulative documentation

In elastic.co/docs (Docs V3), we write docs cumulatively regardless of the branching strategy selected.

What does this mean?

With 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.

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.

Note

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.

How does it change the way we write docs?

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.

In order to achieve this, the markdown source files integrate a tagging system meant to identify:

Which Elastic products and deployment models the content applies to (for example, Elastic Cloud Serverless or Elastic Cloud Hosted).
When a feature goes into a new state as compared to the established base version (for example, being added or going from Beta to GA).

This tagging system is mandatory for all of the public-facing documentation. We refer to it as “applies_to” tags or badges.

How version awareness works in Docs V3

Docs V3 uses a central version config called 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. This logic allows us to label documentation related to unreleased versions as planned, continuously release documentation, and document our Serverless and Elastic Stack offerings in one place.

Tagging products and deployment models

Page-level frontmatter (mandatory)

All documentation pages must include an applies_to tag in the YAML frontmatter. Use YAML frontmatter to indicate each deployment target's availability and lifecycle status.

The applies_to attribute is used to display contextual badges on each page. For the full list of supported keys and values, refer to frontmatter.

Tip

Docs V3 frontmatter also supports a products attribute. This attribute is not surfaced to users on docs pages. Instead, it's used by the elastic.co search to let users filter their docs search results.

There are 3 typical scenarios to start from:

The documentation set or page is primarily about using or interacting with Elastic Stack components or the Serverless UI:
```
---
applies_to:
  stack: ga
  serverless: ga
---
```
The documentation set or page is primarily about orchestrating, deploying or configuring an installation (only include relevant keys):
```
---
applies_to:
  serverless: ga
  deployment:
    ess: ga
    ece: ga
    eck: ga
---
```
The documentation set or page is primarily about a product following its own versioning schema:
```
---
applies_to:
  edot_ios: ga
---
```

It can happen that it’s relevant to identify several or all of these dimensions for a page. Use your own judgement and check existing pages in similar contexts.

		---
applies_to:
  stack: ga
  serverless: ga
  deployment:
    ess: ga
    ece: ga
    eck: ga
---

	

Section or inline contexts (situational)

When 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. For example:

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):
```
---
applies_to:
  stack: ga
  serverless: ga
---

# Spaces

[...]

## Configure a space-level landing page [space-landing-page]
```{applies_to}
serverless: unavailable
```
```

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:

		## Cloud organization level security [cloud-organization-level]
```{applies_to}
deployment:
  ess: ga
serverless: ga
```

[...]

## Orchestrator level security [orchestrator-level]
```{applies_to}
deployment:
  ece: ga
```

[...]

	

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:

		**Spaces** let you organize your content and users according to your needs.

- Each space has its own saved objects.
- {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view.

When should I indicate that something is NOT applicable to a specific context?

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 Elastic Cloud Hosted deployment just requires identifying "Elastic Cloud Hosted" 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:
```
---
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:
```
---
applies_to:
  stack: ga
  serverless: ga
—--

# Spaces

[...]

## Configure a space-level landing page [space-landing-page]
```{applies_to}
serverless: unavailable
```
```

In the previous section, we’ve considered product and deployment availability. Feature lifecycle and version-related changes are communicated as part of the same applies_to tagging logic, by specifying different values to each supported key.

Are you sure your change is related to a specific version? Maybe not…
This is a frequent case. For example: fixing typos, improving styling, adding a long-forgotten setting, etc.
For this case, no specific version tagging is necessary.

A new feature is added to Serverless or Elastic Cloud. How do I tag it?
Cumulative documentation is not meant to replace release notes. If a feature becomes available in Serverless and doesn’t have a particular lifecycle state to call out (preview, beta, deprecated…), it does not need specific tagging.

However, in this scenario, it is important to consider carefully when the change is going to be published.

We do not do date-based tagging for unversioned products.

For unversioned products (typically Serverless and Elastic Cloud Hosted)

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
---
```

For 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
---
```

Document features shared between serverless and Elastic Stack

If a change is released in Serverless and will be released in a future version of the Elastic Stack, you can add both a serverless and stack tag, indicating the version of the Elastic 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 Elastic Stack. To allow for this, Docs V3 displays badges differently 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 Elastic Stack version will render the following badges:

Serverless Stack Planned
After the Elastic Stack version is released, the same badges will render with the version number without any changes to the badge value in the source.

Serverless Stack 9.0.0

Identify multiple states for the same content

applies_to keys accept comma-separated values to specify lifecycle states for multiple product versions. For example:

A feature is added in 9.1 as tech preview and becomes GA in 9.4:
```
applies_to:
  stack: preview 9.1, ga 9.4
```
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:
  deployment:
    ece: deprecated 4.0, removed 4.8
    ess: removed
```

How do these tags behave in the output?

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.

Planned (if the lifecycle is preview, beta, or ga)

Example: Stack Planned
Deprecation planned (if the lifecycle is deprecated)

Example: Stack Deprecation planned
Removal planned (if the lifecycle is removed)

Example: Stack Removal planned

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.

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.