You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/contribute/cumulative-docs/best-practices.md
+173-9Lines changed: 173 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,48 @@
1
1
---
2
-
navigation_title: Best practices
2
+
navigation_title: Guidelines
3
3
---
4
4
5
-
# Best practices for using `applies_to`
5
+
# Cumulative docs guidelines
6
6
7
-
Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs.
7
+
Start by asking yourself:
8
+
9
+
* Does this content vary between products, versions, or deployment types?
10
+
* Is this a feature lifecycle change or just content improvement?
11
+
* Will users benefit from knowing this information?
12
+
13
+
If the answer to at least one of these questions is _yes_, follow these guidelines to write cumulative documentation.
14
+
15
+
## Dimensions of applicability
16
+
17
+
### Type
18
+
19
+
In cumulative documentation, you can use `applies_to` to communicate:
20
+
21
+
***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 tags](#products-and-deployment-models).
22
+
***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 [Tagging version-related changes](#versions).
23
+
24
+
Both types of applicability are added as part of the same `applies_to` tagging logic.
25
+
The type of applicability is the [keys](/contribute/cumulative-docs/reference.md#key)
26
+
and the [feature lifecycle](/contribute/cumulative-docs/reference.md#lifecycle)
27
+
and [version](/contribute/cumulative-docs/reference.md#version) are make up the value.
28
+
29
+
```
30
+
<key>: <lifecycle> <version>
31
+
```
32
+
33
+
### Level
34
+
35
+
For each type of applicability information, you can add `applies_to` metadata at different levels:
36
+
37
+
***Page-level** metadata is **mandatory** and must be included in the frontmatter.
38
+
This defines the overall applicability of the page across products, deployments, and environments.
39
+
***Section-level** annotations allow you to specify different applicability for individual sections
40
+
when only part of a page varies between products or versions.
41
+
% * **Element-level** annotations allow tagging block-level elements like tabs, dropdowns, and admonitions.
42
+
% This is useful for ...
43
+
***Inline** annotations allow fine-grained annotations within paragraphs or definition lists.
44
+
This is useful for highlighting the applicability of specific phrases, sentences,
45
+
or properties without disrupting the surrounding content.
8
46
9
47
## General guidelines
10
48
@@ -18,20 +56,20 @@ Depending on what you're trying to communicate, you can use the following patter
18
56
* Avoid using version numbers in prose adjacent to `applies_to` badge to prevent
19
57
confusion when the badge is rended with `Planned` ahead of a release.
% TO DO: Open an issue to force the order in the code.
67
+
## Order of items
31
68
32
69
**Versions.** Always put the newest version first when listing multiple versions. As a result, the lifecycles should be in reverse order of product development progression, too.
***Always include page-level product and deployment model applicability information**.
91
+
This is _mandatory_ for all pages.
92
+
***Determine if section or inline applicability information is necessary.**
93
+
This _depends on the situation_.
94
+
* For example, if a portion of a page is applicable to a different context than what was specified at the page level,
95
+
clarify in what context it applies using section or inline `applies_to` badges.
96
+
97
+
### Example scenarios [products-and-deployment-models-examples]
98
+
99
+
* Content is primarily about both Elastic Stack components and the Serverless UI ([example](/contribute/cumulative-docs/content-patterns.md#stateful-serverless)).
100
+
* Content is primarily about orchestrating, deploying or configuring an installation ([example](/contribute/cumulative-docs/content-patterns.md#stateful-serverless)).
101
+
* Content is primarily about a product following its own versioning schema ([example]()).
102
+
* A whole page is generally applicable to Elastic Stack 9.0 and to Serverless,
103
+
but one specific section isn’t applicable to Serverless ([example]()).
104
+
* The whole page is generally applicable to all deployment types,
105
+
but one specific paragraph only applies to Elastic Cloud Hosted and Serverless,
106
+
and another paragraph only applies to Elastic Cloud Enterprise ([example]()).
107
+
* Likewise, when the difference is specific to just one paragraph or list item, the same rules apply.
108
+
Just the syntax slightly differs so that it stays inline ([example]()).
% 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.
115
+
% :::
116
+
117
+
% Use `applies_to` in the YAML frontmatter to indicate each deployment target's availability and lifecycle status.
118
+
% The `applies_to` attribute is used to display contextual badges on each page.
119
+
% For the full list of supported keys and values, refer to [](/contribute/cumulative-docs/reference.md#key).
% * 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:
***Ensure your change is related to a specific version.**
134
+
Even though a change is made when a specific version is the latest version,
135
+
it does not mean the added or updated content only applies to that version.
136
+
* For example, you should not use version tagging when fixing typos,
137
+
improving styling, or adding a long-forgotten setting.
138
+
139
+
### Examples [versions-examples]
140
+
141
+
***A new feature is added to {{serverless-short}} or {{ecloud}}. How do I tag it?**
142
+
Cumulative documentation is not meant to replace release notes. 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.
143
+
144
+
However, in this scenario, it is important to consider carefully [when the change is going to be published](/contribute/branching-strategy.md).
145
+
146
+
We do not do date-based tagging for unversioned products.
147
+
148
+
% ### For unversioned products (typically {{serverless-short}} and {{ech}})
By default, we communicate that content does not apply to a certain context by simply **not specifying it**.
171
+
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.
172
+
173
+
This is true for most situations. However, it can still be useful to call it out in a few specific scenarios:
174
+
175
+
* 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:
176
+
177
+
```yml
178
+
---
179
+
applies_to:
180
+
stack: ga
181
+
serverless:
182
+
elasticsearch: ga
183
+
security: ga
184
+
observability: unavailable
185
+
---
186
+
```
187
+
188
+
189
+
* 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:
190
+
191
+
````md
192
+
---
193
+
applies_to:
194
+
stack: ga
195
+
serverless: ga
196
+
—--
197
+
198
+
# Spaces
199
+
200
+
[...]
201
+
202
+
## Configure a space-level landing page [space-landing-page]
0 commit comments