Skip to content

Commit 279c443

Browse files
colleenmcginniscolleenmcginnis
committed
initial outline
1 parent 648393c commit 279c443

File tree

13 files changed

+432
-238
lines changed

13 files changed

+432
-238
lines changed

‎docs/_docset.yml

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,12 @@ toc:
3434
- file: on-the-web.md
3535
- file: move.md
3636
- file: redirects.md
37-
- file: cumulative-docs.md
37+
- folder: cumulative-docs
38+
children:
39+
- file: index.md
40+
- file: reference.md
41+
- file: best-practices.md
42+
- file: content-patterns.md
3843
- file: branching-strategy.md
3944
- file: add-repo.md
4045
- file: release-new-version.md
@@ -110,10 +115,6 @@ toc:
110115
- file: tabs.md
111116
- file: tagged_regions.md
112117
- file: titles.md
113-
- folder: versions
114-
children:
115-
- file: index.md
116-
- file: content-patterns.md
117118
# nested TOCs are only allowed from docset.yml by default
118119
# to prevent them from being nested deeply arbitrarily
119120
# use max_toc_depth to allow deeper nesting (Expert mode, consult with docs team)
@@ -144,7 +145,7 @@ toc:
144145
- folder: deeply-nested
145146
children:
146147
- file: index.md
147-
- file: foo.md
148+
- file: foo.md
148149
- file: bar.md
149150
- folder: baz
150151
children:

‎docs/_snippets/applies_to-key.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
`applies_to` accepts the following keys in this structure:
2+
3+
* `stack`: Applies to the [Elastic Stack](https://www.elastic.co/docs/get-started/the-stack) including any Elastic Stack components.
4+
* `deployment`: Applies to some deployment type(s).
5+
* `eck`: Applies to [Elastic Cloud on Kubernetes](https://www.elastic.co/docs/deploy-manage/deploy/cloud-on-k8s) deployments.
6+
* `ech`: Applies to [Elastic Cloud Hosted](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/cloud-hosted) deployments.
7+
* `ece`: Applies to [Elastic Cloud Enterprise](https://www.elastic.co/docs/deploy-manage/deploy/cloud-enterprise) deployments.
8+
* `self`: Applies to [self-managed](https://www.elastic.co/docs/deploy-manage/deploy/self-managed) deployments.
9+
* `ess`: Applies to the the Elasticsearch Service deployments. {applies_to}`product: deprecated`
10+
:::{note}
11+
Use `ech` instead.
12+
:::
13+
* `serverless`: Applies to [Elastic Cloud Serverless](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/serverless).
14+
* `security`: Applies to Serverless [security projects](https://www.elastic.co/docs/solutions/security/get-started/create-security-project).
15+
* `elasticsearch`: Applies to Serverless [search projects](https://www.elastic.co/docs/solutions/search/serverless-elasticsearch-get-started).
16+
* `observability`: Applies to Serverless [observability projects](https://www.elastic.co/docs/solutions/observability/get-started).
17+
* `product`: Applies to a specific product.
18+
* `ecctl`: Applies to [Elastic cloud control](https://www.elastic.co/docs/reference/ecctl).
19+
* `curator`: Applies to [Elasticsearch Curator](https://www.elastic.co/docs/reference/elasticsearch/curator).
20+
* `apm_agent_dotnet`: Applies to the [Elastic APM .NET agent](https://www.elastic.co/docs/reference/apm/agents/dotnet).
21+
* `apm_agent_go`: Applies to the [Elastic APM Go agent](https://www.elastic.co/docs/reference/apm/agents/go).
22+
* `apm_agent_java`: Applies to the [Elastic APM Java agent](https://www.elastic.co/docs/reference/apm/agents/java).
23+
* `apm_agent_node`: Applies to the [Elastic APM Node.js agent](https://www.elastic.co/docs/reference/apm/agents/nodejs).
24+
* `apm_agent_php`: Applies to the [Elastic APM PHP agent](https://www.elastic.co/docs/reference/apm/agents/php).
25+
* `apm_agent_python`: Applies to the [Elastic APM Python agent](https://www.elastic.co/docs/reference/apm/agents/python).
26+
* `apm_agent_ruby`: Applies to the [Elastic APM Ruby agent](https://www.elastic.co/docs/reference/apm/agents/ruby).
27+
* `apm_agent_rum`: Applies to the [APM RUM JavaScript agent](https://www.elastic.co/docs/reference/apm/agents/rum-js).
28+
* `edot_collector`: Applies to the [Elastic Distribution of OpenTelemetry Collector](https://www.elastic.co/docs/reference/opentelemetry/edot-collector/).
29+
* `edot_ios`: Applies to the [Elastic Distribution of OpenTelemetry iOS](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/ios/).
30+
* `edot_android`: Applies to the [Elastic Distribution of OpenTelemetry Android](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/android/).
31+
* `edot_dotnet`: Applies to the [Elastic Distribution of OpenTelemetry .NET](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/dotnet/).
32+
* `edot_java`: Applies to the [Elastic Distribution of OpenTelemetry Java](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/java/).
33+
* `edot_node`: Applies to the [Elastic Distribution of OpenTelemetry Node.js](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/nodejs/).
34+
* `edot_php`: Applies to the [Elastic Distribution of OpenTelemetry PHP](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/php/).
35+
* `edot_python`: Applies to the [Elastic Distribution of OpenTelemetry Python](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/python/).
36+
* `edot_cf_aws`: Applies to the [Elastic Distribution of OpenTelemetry Cloud Forwarder](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/).

‎docs/_snippets/applies_to-lifecycle.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
`applies_to` accepts the following lifecycle states:
2+
3+
* `preview`
4+
* `beta`
5+
* `deprecated`
6+
* `removed`
7+
* `unavailable`
8+
* `ga`

‎docs/_snippets/applies_to-version.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
`applies_to` accepts the following version formats:
2+
3+
* `Major.Minor`
4+
* `Major.Minor.Patch`
5+
6+
:::{note}
7+
Regardless of the version format used in the source file,
8+
the version number will always be rendered in the `Major.Minor.Patch` format.
9+
:::

‎docs/contribute/cumulative-docs/_snippets/content-patterns-list.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
% | Approach | Use case |
2+
% | --- | --- |
3+
% | [Page-level `applies` tags](/versions/content-patterns.md#page-level-applies-tags) | Provide signals that a page applies to the reader. |
4+
% | [Section/heading-level `applies` tags](/versions/content-patterns.md#sectionheading-level-applies-tags) | Provide signals about a section’s scope so a user can choose to read or skip it as needed. |
5+
% | [Tabs](/versions/content-patterns.md#tabs) | Provide two sets of procedures when one or more steps in a process differs between contexts or versions. |
6+
% | [Callouts](/versions/content-patterns.md#callouts) | Draw attention to happy differences and basic clarifications. |
7+
% | [Prose](/versions/content-patterns.md#prose) | - Identify features in a list of features that are exclusive to a specific context, or that were introduced in a specific version<br>- List differing requirements, limits, and other simple, mirrored facts<br>- Provide clarifying or secondary information<br>- Explain differences with a "why" (e.g. comparative overviews) |
8+
% | [Sibling pages](/versions/content-patterns.md#sibling-pages) | When the information is too complex to be addressed with only the other content patterns. See specific examples in the sibling pages section. |
9+
10+
% | [List item suffixes](/versions/content-patterns.md#list-item-suffixes) | Identify features in a **list of features** that are exclusive to a specific context, or that were introduced in a specific version. |
11+
% | [Sibling bullets](/versions/content-patterns.md#sibling-bullets) | List differing requirements, limits, and other simple, mirrored facts. |

‎docs/contribute/cumulative-docs/best-practices.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
navigation_title: Best practices
3+
---
4+
5+
# Best practices for using `applies_to`
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.
8+
9+
## General guidelines
10+
11+
% Reference: Slack conversation
12+
* The `applies_to` badges should not require contributors to add specific Markdown real estate
13+
to the page layout (such as a specific `Version` column in a table).
14+
Instead, contributors should be able to add them anywhere they need, and the system should
15+
be in charge of rendering them clearly.
16+
17+
* Always put the newest version first when [listing multiple versions]().
18+
19+
% Reference: https://github.com/elastic/kibana/pull/229485/files#r2231876006
20+
* Avoid using version numbers in prose adjacent to `applies_to` badge to prevent
21+
confusion when the badge is rended with `Planned` ahead of a release.
22+
23+
% Reference: https://github.com/elastic/kibana/pull/229485/files#r2231850710
24+
* Create hierarchy of versioned information??
25+
26+
% Reference: https://elastic.github.io/docs-builder/versions/#defaults-and-hierarchy
27+
* Do not assume a default deployment type, stack flavor, product version, or project type.
28+
Treat all flavors and deployment types equally. Don't treat one as the "base" and the other as the "exception".
29+
30+
% Reference: https://elastic.github.io/docs-builder/versions/#defaults-and-hierarchy
31+
% Needs work...
32+
* List keys in the same order for consistency. This order reflects organizational priorities.
33+
* Serverless
34+
* Stack
35+
* Elastic Cloud Hosted
36+
* Elastic Cloud on Kubernetes
37+
* Elastic Cloud Enterprise
38+
* Self-managed
39+
40+
## Placement of labels
41+
42+
% Reference: https://github.com/elastic/docs-builder/issues/1574
43+
* **Headings**: Use section annotations immediately after the heading.
44+
Do _not_ use inline annotations with headings, which will cause rendering issues in "On this page".
45+
46+
% Reference: https://github.com/elastic/kibana/pull/229485/files
47+
* **Definition lists**: If the `applies_to` badge is relevant to the entire contents of the list item,
48+
put it at the end of the term (on the same line).
49+
50+
% Reference: TBD
51+
* **Ordered and unordered lists**: Reorganize content as needed so the `applies_to` badge is relevant
52+
to the entire contents of the list item. The recommended placement of the badge varies:
53+
* If the purpose of the list is to illustrate the difference between several applications (deployment types,
54+
products, lifecycles, versions, etc.) put an `applies_to` badge at the start of each item.
55+
* If the list just happens to have one or more items that are only relevant to specific application
56+
(deployment type, product, lifecycle, version, etc.) put the `applies_to` badge at the end of the list item.
57+
58+
% Reference: Slack conversation
59+
* **Tables**: The recommended placement in tables varies:
60+
* If the `applies_to` badge is relevant to the entire row, add the badge to the end of
61+
the first column. For example, a table that contains one setting per row and a new setting
62+
is added in 9.1.0.
63+
* If the `applies_to` badge is relevant to one cell or part of a cell, add the badge to the
64+
end of the line it applies to. For example, a new property is available in 9.1.0 for a setting
65+
that already existed before 9.1.0.
66+
% Reference: https://github.com/elastic/kibana/pull/229485/files#r2231856744
67+
If needed, break the contents of the cell into multiple lines using `<br>` to isolate the
68+
content you're labeling.
69+
70+
## Scenarios [scenarios]
71+
72+
There are several scenarios you will likely run into at some point when contributing to the docs.
73+
74+
### Feature in beta or technical preview is removed [beta-preview-removed]
75+
76+
If a feature in beta or technical preview is removed without going GA,
77+
[list both || remove the beta/preview version]
78+
in the `applies_to` badge.
79+
80+
% TO DO: Copy over example content https://github.com/elastic/kibana/pull/229485/files#r2231843057
81+
**Example: A beta option was removed one minor after it was introduced**
82+
83+
::::{tab-set}
84+
:::{tab-item} Visual
85+
:::
86+
:::{tab-item} Syntax
87+
:::
88+
::::
89+
90+
### Code block change between versions [code-blocks]
91+
92+
If the content of a code block changes between versions,
93+
you have a couple options depending on the nature of the change.
94+
95+
#### Content is added or removed [code-blocks-added-removed]
96+
97+
Use code callouts to point out lines that have changed over time.
98+
99+
**Example: One new option is available**
100+
101+
::::{tab-set}
102+
:::{tab-item} Visual
103+
:::
104+
:::{tab-item} Syntax
105+
:::
106+
::::
107+
108+
#### Content is replaced [code-blocks-replaced]
109+
110+
Use a tab for each version that contains a change.
111+
112+
**Example**
113+
114+
::::{tab-set}
115+
:::{tab-item} Visual
116+
:::
117+
:::{tab-item} Syntax
118+
:::
119+
::::
120+
121+
### Adjacent block elements change between versions [adjacent-block-elements]
122+
123+
**Example**
124+
125+
::::{tab-set}
126+
:::{tab-item} Visual
127+
:::
128+
:::{tab-item} Syntax
129+
:::
130+
::::
131+
132+
### Images change between versions [images]
133+
134+
#### Screenshots
135+
136+
Follow these principles to use screenshots in our unversioned documentation system:
137+
138+
* Reduce screenshots when they don’t explicitly add value.
139+
* When adding a screenshot, determine the minimum viable screenshot and whether it can apply to all relevant versions.
140+
* Take and maintain screenshots for only the most recent version, with very few exceptions that should be considered on a case-by-case basis.
141+
* In case of doubt, prioritize serverless.
142+
143+
**Example**
144+
145+
::::{tab-set}
146+
:::{tab-item} Visual
147+
:::
148+
:::{tab-item} Syntax
149+
:::
150+
::::
151+
152+
### UI changes between versions [ui]
153+
154+
**Example**
155+
156+
::::{tab-set}
157+
:::{tab-item} Visual
158+
:::
159+
:::{tab-item} Syntax
160+
:::
161+
::::
162+
163+
### One sentence in a paragraph changes between versions [inline-elements]
164+
165+
**Example**
166+
167+
::::{tab-set}
168+
:::{tab-item} Visual
169+
:::
170+
:::{tab-item} Syntax
171+
:::
172+
::::
173+
174+
### Table columns, rows, or cells change between versions
175+
176+
#### Content is added or removed
177+
178+
**Example**
179+
180+
::::{tab-set}
181+
:::{tab-item} Visual
182+
:::
183+
:::{tab-item} Syntax
184+
:::
185+
::::
186+
187+
#### Content is replaced
188+
189+
**Example**
190+
191+
::::{tab-set}
192+
:::{tab-item} Visual
193+
:::
194+
:::{tab-item} Syntax
195+
:::
196+
::::

0 commit comments

Comments
 (0)