Skip to content

Commit 792b2ea

Browse files
apply suggestions from code review
Co-authored-by: florent-leborgne <[email protected]>
1 parent 3560d44 commit 792b2ea

File tree

2 files changed

+11
-9
lines changed

2 files changed

+11
-9
lines changed

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,15 @@ At a high level, you should follow these badge placement principles:
2121
* Consider scanning patterns - readers often scan for relevant information
2222
* Ensure badges don't break the natural flow of content
2323
* Use consistent placement patterns within similar content types
24+
* Consider visual grouping - readers must naturally associate the badge with its corresponding content, no more, no less
2425

2526
## Specific elements
2627

2728
There are more specific guidelines on badge placement to follow when using specific elements.
2829

2930
### Headings
3031

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+
Use [section annotations](/syntax/applies.md#section-annotations) on the next line 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.
3233

3334
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.
3435

@@ -50,7 +51,7 @@ Do **not** use [inline annotations](/syntax/applies.md#inline-annotations) with
5051

5152
### Definition lists
5253

53-
The recommended placement of `applies_to` badges in definition lists varies based what part(s) of the list item relate to the badge.
54+
The recommended placement of `applies_to` badges in definition lists varies based on what part(s) of the list item relate to the badge.
5455

5556
#### 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]
5657

docs/contribute/cumulative-docs/example-scenarios.md

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -138,10 +138,7 @@ how it is labeled depends on if the functionality is in technical preview, beta,
138138

139139
### If the section lifecycle is the same as the page level [unversioned-added-same]
140140

141-
% FOR THE REVIEWER: IS THERE AN EXAMPLE?
142-
% I actually couldn't find an example where unversioned content was added
143-
% without also adding content for a versioned product.
144-
For example, on the [<page>](#) page we added content about new <something> functionality that was added to Serverless in GA.
141+
For example, on the [Project settings](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/project-settings#obs-serverless-project-features) page we added content about the Observability Logs Essentials feature tier, that was added to Serverless in GA.
145142
Since the page's frontmatter already includes `serverless: ga`, there is no need to label the added content.
146143

147144
:::::{tab-set}
@@ -195,9 +192,7 @@ applies_to:
195192

196193
### If the section lifecycle is different than the page level
197194

198-
% FOR THE REVIEWER: IS THERE AN EXAMPLE?
199-
% I actually couldn't find an example of this scenario.
200-
For example, on the [<page>](#) page we added content about new <something> functionality that was added to Serverless in preview.
195+
For example, on the [Dashboard controls](https://www.elastic.co/docs/explore-analyze/dashboards/add-controls#add-esql-control) page we added content about new ES|QL controls functionality that was added to Serverless in preview.
201196
Since this is different than the page-level applicability in the frontmatter, `serverless: ga`,
202197
label the content about the new functionality with `serverless: preview`.
203198

@@ -480,6 +475,12 @@ In cases where only a small visual detail differs (for example, a button label o
480475
**Example**: As of the Elastic Stack 9.1.0 release, there are no examples of this approach being used in live docs
481476
except for with images used in workflows.
482477

478+
### Solution C: Keep the screenshot aligned with the latest version [screenshot-latest]
479+
480+
In cases where the screenshot is rather conceptually demonstrating a capability, it's fine not to version it.
481+
482+
For example, versioning the screenshot on the [Dashboards](https://www.elastic.co/docs/explore-analyze/dashboards) parent page would not add tremendous value unless the capability drastically evolves.
483+
483484
## Multiple adjacent block elements vary [multiple-block]
484485

485486
### Solution A: Use tabs [multiple-block-tabs]

0 commit comments

Comments
 (0)