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
% FOR THE REVIEWER: SHOULD THESE ACTUALLY BE THE SAME?
28
-
% In the existing docs (https://elastic.github.io/docs-builder/contribute/cumulative-docs/#section-or-inline-contexts-situational),
29
-
% we say to treat Stack/Serverless and deployment types differently.
30
-
% Should we?
31
-
## Section applicability differs from page applicability [page-section-varies]
27
+
28
+
## Section applicability differs from page-level applicability [page-section-varies]
32
29
33
30
When a section has different applicability than the applicability indicated at the
34
31
page level in the frontmatter, use section-level `applies_to` badges.
35
32
36
-
### If labeling deployment modes [one-section]
33
+
### If labeling deployment modes [page-section-varies-deployment]
34
+
35
+
<!--
36
+
TO DO: Consider other alternative titles:
37
+
* If labeling parallel content on a single page
38
+
* If labeling applicable vs. not applicable
39
+
-->
40
+
41
+
<!--
42
+
TO DO: Please make this better
43
+
-->
44
+
When a documentation set or page is primarily about orchestrating, deploying,
45
+
or configuring an installation, it usually includes parallel content about multiple
46
+
deployment modes (the reader picks one of several sections that is applicable to them).
47
+
48
+
% Contributor experience
49
+
In this case, docs contributors include all the deployment types that are mentioned
50
+
throughout the page in the frontmatter `applies_to`, and in each section they include
51
+
only the applicable deployment modes using section-level `applies_to`.
37
52
53
+
% Reader experience
54
+
The reader should assume that content in a section with a section-level `applies_to` is
55
+
not applicable to any deployment modes that are omitted.
56
+
57
+
:::{tip}
58
+
**Don’t overload with exclusions unless it is necessary.**
59
+
In content that is primarily about deployment modes, we do not include `unavailable` badges
60
+
for anything in `applies_to` > `deployment`.
61
+
:::
62
+
63
+
% Example
38
64
For example, the content on the [Security](https://www.elastic.co/docs/deploy-manage/security) page is generally applicable to all deployment types, but the first section only applies to Elastic Cloud Hosted and Serverless:
39
65
40
66
* In the frontmatter, specify that the content on the page applies to all deployment types unless otherwise specified.
41
67
* In a section-level annotation, specify that the content only applies to `ech` and `serverless`.
**Don’t overload with exclusions unless it is necessary.**
76
-
77
-
% FOR THE REVIEWER: IS THIS TRUE?
78
-
In this example, we expect the reader to understand that in sections where only some deployment types are listed,
79
-
the content is only applicable to the deployment types listed in the section-level annotation
80
-
(and is _not_ applicable to the deployment types that are listed at the page level,
81
-
but are omitted from section-level annotation).
82
-
:::
83
-
84
100
:::{tip}
85
101
Likewise, when the difference is specific to just one paragraph or list item, the same rules apply.
86
102
Just the syntax slightly differs so that it stays inline: `` {applies_to}`ech: ga` {applies_to}`serverless: ga` ``.
87
103
:::
88
104
89
-
### If labeling serverless and stateful [not-one-section]
105
+
### If labeling serverless vs. stateful [page-section-varies-product]
90
106
107
+
<!--
108
+
TO DO: Consider other alternative titles:
109
+
* If labeling versioned products or serverless vs. stateful
110
+
* If labeling available vs. unavailable
111
+
-->
112
+
113
+
<!--
114
+
TO DO: Please make this better
115
+
-->
116
+
When a documentation set or page is primarily about using a product following its own
117
+
versioning schema or some combination of Elastic Stack components and the Serverless UI,
118
+
it usually includes content that is meant to be used together (i.e. not parallel sections
119
+
like in [If labeling deployment modes](#page-section-varies-deployment)), but is only
120
+
available in specific versions or either serverless or stateful.
121
+
122
+
% Contributor experience
123
+
In this case, docs contributors should include the following at the page level:
124
+
125
+
*`stack` with the lowest version that applies to any content (unless it is lower
126
+
than the base version, {{version.stack.base}}, in which case omit the version number altogether)
127
+
*`serverless` if applicable
128
+
129
+
Then if a section contains content that applies to a different context than what is
130
+
defined at the page level, include section-level `applies_to` only with the items
131
+
that are different than the page-level `applies_to`.
132
+
133
+
% Reader experience
134
+
The reader should assume that content in a section with a section-level `applies_to`
135
+
is applicable to all the contexts included in the page-level `applies_to` unless
136
+
explicitly stated.
137
+
138
+
:::{tip}
139
+
**Don’t overload with badges that restate the page-level applicability.**
140
+
In content that is primarily about serverless vs. stateful, use `unavailable`
141
+
if functionality is not available at all in `serverless` or `stack`.
142
+
Do not use `unavailable` for specific `stack` versions.
143
+
Instead, include the lifecycle and version and the fact that it is not applicable
144
+
to other versions will be implied.
145
+
:::
146
+
147
+
% Example
91
148
For example, if a whole page is generally applicable to Elastic Stack 9.0.0 and to Serverless, but one specific section isn’t applicable to Serverless. The content on the [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) page is generally applicable to both Serverless and stateful, but one section only applies stateful:
92
149
93
150
* In the frontmatter, specify that the content on the page applies to both unless otherwise specified.
94
-
95
-
% FOR THE REVIEWER: WHICH IS CORRECT?
96
-
% The existing docs and the "real" example in the wild use different strategies.
97
-
% Do we include `stack: ga` in the section annotation or not?
98
-
* In a section-level annotation, specify that the content is `ga` in `stack` and is `unavailable` in `serverless`.
151
+
* In a section-level annotation, specify that the content is `unavailable` in `serverless`.
0 commit comments