Skip to content

Commit a673f32

Browse files
colleenmcginniscolleenmcginnis
committed
finish building out badge placement page
1 parent 66076ea commit a673f32

13 files changed

+484
-386
lines changed

‎docs/_docset.yml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,9 @@ toc:
3939
- folder: cumulative-docs
4040
children:
4141
- file: index.md
42-
- file: best-practices.md
43-
- file: content-patterns.md
42+
- file: guidelines.md
43+
- file: badge-placement.md
44+
- file: example-scenarios.md
4445
- file: reference.md
4546
- file: branching-strategy.md
4647
- file: add-repo.md

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
% | Approach | Use case |
22
% | --- | --- |
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. |
3+
% | [Page-level `applies` tags](/versions/example-scenarios.md#page-level-applies-tags) | Provide signals that a page applies to the reader. |
4+
% | [Section/heading-level `applies` tags](/versions/example-scenarios.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/example-scenarios.md#tabs) | Provide two sets of procedures when one or more steps in a process differs between contexts or versions. |
6+
% | [Callouts](/versions/example-scenarios.md#callouts) | Draw attention to happy differences and basic clarifications. |
7+
% | [Prose](/versions/example-scenarios.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/example-scenarios.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. |
99

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. |
10+
% | [List item suffixes](/versions/example-scenarios.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/example-scenarios.md#sibling-bullets) | List differing requirements, limits, and other simple, mirrored facts. |

‎docs/contribute/cumulative-docs/badge-placement.md

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
navigation_title: Badge placement
3+
---
4+
5+
% Audience: Technical writers and other frequent docs contributors
6+
% Goals:
7+
% * Provide guidance on badge placement in specific situations
8+
9+
# `applies_to` badge placement
10+
11+
As you continue contributing to documentation and more versions are released,
12+
you might have questions about how to integrate `applies_to` badges in
13+
cumulative documentation.
14+
15+
## General principles
16+
17+
% Source: Brandon's PR review comment
18+
At a high level, you should follow these badge placement principles:
19+
20+
* Place badges where they're most visible but least disruptive to reading flow
21+
* Consider scanning patterns - readers often scan for relevant information
22+
* Ensure badges don't break the natural flow of content
23+
* Use consistent placement patterns within similar content types
24+
25+
## Specific elements
26+
27+
More specific guidance in common situations is outlined below.
28+
29+
### Headings
30+
31+
Use [section annotations](/syntax/applies.md#section-annotations) immediately after a heading when the entire content between that heading and the next [heading](/syntax/headings.md) of the same or higher level is version or product-specific.
32+
33+
For example, in the [Semantic text field type](https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/semantic-text#custom-by-pipelines) page, all the content in this section is only applicable to Elastic Stack versions 9.0.0 and later.
34+
35+
::::{image} ./images/heading-correct.png
36+
:screenshot:
37+
:alt: Correct use of applies_to with headings
38+
::::
39+
40+
:::{warning}
41+
Do **not** use [inline annotations](/syntax/applies.md#inline-annotations) with headings, which will cause rendering issues in _On this page_.
42+
43+
::::{image} ./images/heading-incorrect.png
44+
:screenshot:
45+
:alt: Rendering error when using inline applies_to with headings
46+
::::
47+
:::
48+
49+
50+
### Definition lists
51+
52+
The recommended placement of `applies_to` badges in definition lists varies based what part(s) of the list item relate to the badge.
53+
54+
#### If the badge is relevant to the entire contents of a list item, put it at the end of the term [definition-list-item-full]
55+
56+
This means using an inline annotation at the end of the same line as the term. For example, on the Kibana [Advanced settings](https://www.elastic.co/docs/reference/kibana/advanced-settings#kibana-banners-settings) page, the entire `banners:linkColor` option is only available in Elastic Stack 9.1.0 and later.
57+
58+
:::{image} ./images/definition-list-entire-item.png
59+
:screenshot:
60+
:alt: Correct use of applies_to with definition list item
61+
:::
62+
63+
:::{warning}
64+
Do **not** put the `applies_to` badge at the beginning or end of the definition if it relates to the entire contents of the item.
65+
66+
::::{image} ./images/definition-list-item-incorrect.png
67+
:screenshot:
68+
:alt: Incorrectly using inline applies_to with a definition list item
69+
::::
70+
:::
71+
72+
#### If the badge is only relevant to a portion of the definition, follow the appropriate placement guidelines for the elements used in the definition [definition-list-item-part]
73+
74+
This might include labeling just one of multiple paragraphs, or one item in an ordered or unordered list. For example, on the [Google Gemini Connector page](https://www.elastic.co/docs/reference/kibana/connectors-kibana/gemini-action-type#gemini-connector-configuration), the default model is different depending on the deployment type and version of the Elastic Stack. These differences should be called out with their own `applies_to` badges.
75+
76+
::::{image} ./images/definition-list-portion-correct.png
77+
:screenshot:
78+
:alt: Correctly using inline applies_to in a portion of a definition list item
79+
::::
80+
81+
### Ordered and unordered lists
82+
83+
Reorganize content as needed so the `applies_to` badge is relevant to the entire contents of the list item.
84+
The recommended placement of the badge varies based on the purpose of the list.
85+
86+
#### If the purpose of the list is to illustrate the difference between situations, put a badge at the start of each item [list-compare-applies_to]
87+
88+
This could mean distinguishing between deployment types, products, lifecycles, or versions.
89+
Placing the badge at the beginning of the list item, allows the reader to scan the list for the item that is relevant to them.
90+
91+
For example, the [Alerting and action settings in Kibana](https://www.elastic.co/docs/reference/kibana/configuration-reference/alerting-settings) page lists how the default value for the `xpack.actions.preconfigured.<connector-id>.config.defaultModel` setting varies in Serverless/Stack and across versions.
92+
93+
::::{image} ./images/list-correct.png
94+
:screenshot:
95+
:alt:
96+
::::
97+
98+
#### If the list just happens to have one or more items that are only relevant to a specific situation, put the badge at the end of the list item [list-other]
99+
100+
Placing the badge at the end of the list item maintains the flow of the list without distracting the reader with badges while still making it clear that the content in that list item is only applicable to the specified situation.
101+
102+
For example, the [Add filter controls](https://www.elastic.co/docs/explore-analyze/dashboards/add-controls) page lists ways to configure ES|QL controls. Only one of the ways they can be controlled was added for the first time in 9.1.0.
103+
104+
::::{image} ./images/list-misc-correct.png
105+
:screenshot:
106+
:alt:
107+
::::
108+
109+
110+
% Reference: Slack conversation
111+
### Tables
112+
113+
The recommended placement in tables varies based on what part(s) of the table related to the `applies_to` label.
114+
115+
#### If the badge is relevant to the entire row, add the badge to the end of the first column [table-row]
116+
117+
Add the badge to the end of the first column to indicate that it applies to all cells in a row.
118+
119+
For example, the [Streaming Input](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-streaming#_metrics_14) page includes a table that contains one setting per row and a new setting is added in 9.0.4.
120+
121+
::::{image} ./images/table-entire-row-correct.png
122+
:screenshot:
123+
:alt:
124+
::::
125+
126+
:::{warning}
127+
Do **not** create a new column just for versions.
128+
The `applies_to` badges should _not_ require contributors to add specific Markdown real estate to the page layout.
129+
Instead, contributors should be able to add them anywhere they need, and the system should be in charge of rendering them clearly.
130+
131+
::::{image} ./images/table-entire-row-incorrect.png
132+
:screenshot:
133+
:alt:
134+
::::
135+
:::
136+
137+
#### If the badge is relevant to one cell or part of a cell, add the badge to the cell it applies to [table-cell]
138+
139+
Add the badge to the cell to indicate that it applies to that one cell only.
140+
141+
For example, the [Collect application data](https://www.elastic.co/docs/solutions/observability/apm/collect-application-data#_capabilities) page includes a table that compares functionality across two methods for collecting APM data, and only one of the methods is in technical preview.
142+
143+
::::{image} ./images/table-one-cell-correct.png
144+
:screenshot:
145+
:alt:
146+
::::
147+
:::
148+
149+
:::{tip}
150+
If the one cell that the badge applies to is in the first column, consider formatting the content
151+
using something other than a table (for example, a definition list) to avoid confusion with the
152+
[previous scenario](#table-row) in which adding the badge to the first column indicates that the
153+
badge applies to the whole row.
154+
:::
155+
156+
#### If the badge is relevant to part of a cell, add the badge to the end of the line it applies to [table-cell-part]
157+
158+
For example, the [Parse AWS VPC Flow Log](https://www.elastic.co/docs/reference/beats/filebeat/processor-parse-aws-vpc-flow-log) page includes new information relevant to 9.2.0 and later about a setting that already existed before 9.2.0.
159+
160+
::::{image} ./images/table-part-of-cell-correct.png
161+
:screenshot:
162+
:alt:
163+
::::
164+
:::
165+
166+
% Reference: https://github.com/elastic/kibana/pull/229485/files#r2231856744
167+
:::{tip}
168+
If needed, break the contents of the cell into multiple lines using `<br>` to isolate the content you're labeling or consider not using a table to format the related content.
169+
:::
170+
171+
### Tabs
172+
173+
In the future ([elastic/docs-builder#1436](https://github.com/elastic/docs-builder/issues/1436)), tabs will be able to accept `applies_to` information. Until then, if an `applies_to` badge is relevant to the entire tab item, add the badge to the beginning of the content.
174+
175+
% TO DO: Add example
176+
% <image>
177+
178+
### Admonitions
179+
180+
In the future ([elastic/docs-builder#1436](https://github.com/elastic/docs-builder/issues/1436)), admonitions will be able to accept `applies_to` information. Until then, if an `applies_to` badge is relevant to the entire admonition, add the badge to the beginning of the content.
181+
182+
::::{image} ./images/admonition-correct.png
183+
:screenshot:
184+
:alt:
185+
::::
186+
187+
### Dropdowns
188+
189+
In the future ([elastic/docs-builder#1436](https://github.com/elastic/docs-builder/issues/1436)), dropdowns will be able to accept `applies_to` information. Until then, if an `applies_to` badge is relevant to the entire dropdown, add the badge to the beginning of the content.
190+
191+
% TO DO: Add example
192+
% <image>
193+
194+
### Code blocks
195+
196+
To specify `applies_to` information for a code block, refer to [](/contribute/cumulative-docs/example-scenarios.md#code-block).
197+
198+
### Images
199+
200+
To specify `applies_to` information for an image, refer to [](/contribute/cumulative-docs/example-scenarios.md#screenshot).

0 commit comments

Comments
 (0)