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/example-scenarios.md
+61-61Lines changed: 61 additions & 61 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,45 +30,57 @@ the Serverless UI, add both the `stack` and `serverless` keys to the `applies_to
30
30
When a section has different applicability than the applicability indicated at the
31
31
page level in the frontmatter, use section-level `applies_to` badges.
32
32
33
-
### If labeling deployment modes [page-section-varies-deployment]
33
+
### If labeling serverless vs. stateful [page-section-varies-product]
34
34
35
35
<!--
36
36
TO DO: Consider other alternative titles:
37
-
* If labeling parallel content on a single page
38
-
* If labeling applicable vs. not applicable
37
+
* If labeling versioned products or serverless vs. stateful
38
+
* If labeling available vs. unavailable
39
39
-->
40
40
41
41
<!--
42
42
TO DO: Please make this better
43
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).
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.
47
49
48
50
% 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`.
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`.
52
60
53
61
% 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.
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.
56
65
57
66
:::{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`.
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.
61
73
:::
62
74
63
75
% Example
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:
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:
65
77
66
-
* In the frontmatter, specify that the content on the page applies to all deployment types unless otherwise specified.
67
-
* In a section-level annotation, specify that the content only applies to `ech` and`serverless`.
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`.
@@ -77,19 +89,18 @@ For example, the content on the [Security](https://www.elastic.co/docs/deploy-ma
77
89
````
78
90
---
79
91
applies_to:
80
-
deployment: all
92
+
stack: ga
93
+
serverless: ga
81
94
---
82
95
83
-
# Security
96
+
# Spaces
84
97
85
98
[...]
86
99
87
-
## Managed security in Elastic Cloud
100
+
## Configure a space-level landing page [space-landing-page]
88
101
89
102
```{applies_to}
90
-
deployment:
91
-
ech: ga
92
-
serverless: ga
103
+
serverless: unavailable
93
104
```
94
105
95
106
[...]
@@ -99,60 +110,48 @@ serverless: ga
99
110
100
111
:::{tip}
101
112
Likewise, when the difference is specific to just one paragraph or list item, the same rules apply.
102
-
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` ``.
103
114
:::
104
115
105
-
### If labeling serverless vs. stateful [page-section-varies-product]
116
+
### If labeling deployment modes [page-section-varies-deployment]
106
117
107
118
<!--
108
119
TO DO: Consider other alternative titles:
109
-
* If labeling versioned products or serverless vs. stateful
110
-
* If labeling available vs. unavailable
120
+
* If labeling parallel content on a single page
121
+
* If labeling applicable vs. not applicable
111
122
-->
112
123
113
124
<!--
114
125
TO DO: Please make this better
115
126
-->
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.
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).
121
130
122
131
% 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
+
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`.
132
135
133
136
% 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
+
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.
137
139
138
140
:::{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.
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`.
145
144
:::
146
145
147
146
% Example
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:
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:
149
148
150
-
* In the frontmatter, specify that the content on the page applies to both unless otherwise specified.
151
-
* In a section-level annotation, specify that the content is `unavailable` in`serverless`.
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