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