-
Notifications
You must be signed in to change notification settings - Fork 19
Adds changes to the applies_to
page
#1325
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
applies_to
pageapplies_to
page
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks @charlotte-hoblik your changes about the updates look great, I just think we should take the opportunity to improve the overall structure of the page now that the information is more mature. I didn't give this a 100% thorough review, but should be enough to build upon your work.
security: unavailable | ||
elasticsearch: beta | ||
observability: deprecated | ||
product: preview 9.5, deprecated 9.7 | ||
--- | ||
|
||
# Applies to |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we can restructure the page now that we have more info and have more logical progression:
Something like:
- Intro
- Syntax
- When and where to use
applies_to
← new grouped section
- Intro/explain that each level has slightly different syntax.
- Mention stuff currently in 'when to use'
- Levels:
- Page-level (required)
- Section-level
- Inline
- Structured model (Maybe could have better heading name like "Metadata structure" or something)
- Examples
I'm not married to any specific ordering here apart from having more context and explanations up top. :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
and maybe we can weave examples into other sections and remove the standalone examples #maybe
Co-authored-by: Liam Thompson <[email protected]>
Co-authored-by: Liam Thompson <[email protected]>
@charlotte-hoblik I think we could improve the flow in the Syntax section, namely by moving lifecycle up higher:
|
Co-authored-by: Liam Thompson <[email protected]>
Co-authored-by: Liam Thompson <[email protected]>
Co-authored-by: Liam Thompson <[email protected]>
Thank you, @leemthompo for the helpful feedback and suggestions! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you thank you @charlotte-hoblik
Your changes already make this page so much better. 🙇
I'm leaving some comments that are mostly small clarifications or suggestions to add more overall context to the core purpose of these applies_to tag.
* `unavailable` | ||
* `ga` | ||
|
||
#### Version | ||
Both versioned and unversioned products use the same lifecycle tags, but only versioned products can be marked `ga`. Unversioned products are considered `ga` by default and don’t need specification. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd remove this sentence.
Unless I've missed a recent development, all products need a lifecycle tag. If a product key is entered without a value, it is not displayed in the output. For example: serverless: ga
will show a serverless badge. While serverless:
will show nothing.
I believe that what you're trying to say here, you are already saying it correctly later in this document when talking about unversioned products:
* When a change is released in ga, it **doesn’t need any specific tagging**.
stack: beta all | ||
serverless: beta | ||
``` | ||
✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments. | |
✅ Use `applies_to` tags when features change state (`preview`, `beta`, `ga`, `deprecated`, `removed`) or when availability differs across deployments and environments. |
Really like those do/don'ts. I'd move them after the itemized list so we start with explanations on page/section/inline level. We can maybe have some more as well to help clarify some assumptions:
"""
Not every case requires an applies_to tag:
✅ Use applies_to
tags to indicate which product or deployment type content applies to. This is mandatory for every page
❌ You don't need to tag every section or paragraph. Only do if the context or applicability changes from what has been established before
✅ Use applies_to
tags when features change state in a specific update or release
❌ if the product is not versioned (meaning that all users are always on the latest version like serverless or cloud), you do not need to tag a new GA feature
❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes.
"""
^^ Just examples, I'm not precious about those.
# Applies to | ||
|
||
Allows you to annotate a page or section's applicability. | ||
The `applies_to` metadata allows you to specify which product versions, deployment types, and environments a specific page, section, or line applies to. Documentation published using Elastic Docs V3 follows a [cumulative model](../contribute/index.md) where a single page covers multiple versions cumulatively over time, instead of creating separate pages for each minor release. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The `applies_to` metadata allows you to specify which product versions, deployment types, and environments a specific page, section, or line applies to. Documentation published using Elastic Docs V3 follows a [cumulative model](../contribute/index.md) where a single page covers multiple versions cumulatively over time, instead of creating separate pages for each minor release. | |
Starting with Elastic Stack version 9.0, ECE 4.0, and ECK 3.0, documentation is organized around user goals instead of per product, and each page stays valid over time and incorporates version-specific changes directly within the content using a [cumulative approach](../contribute/index.md#cumulative-docs). | |
That means that instead of creating separate pages for each product and release, we update the same page with product-specific and version-specific details. | |
In order to achieve this in a standardized way, the markdown source files integrate a **tagging system** meant to identify: | |
* Which Elastic products and deployment models the content applies to. | |
* When a feature goes into a new state as compared to the established base version. | |
This is what the `applies_to` metadata is for. |
Borrowed and adjusted from #1324
I reckon that's a bit long as an intro, feel free to try to shorten :D
``` | ||
|
||
`all` can also be specified at a version level | ||
## When and where to use `applies_to` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would move this section (until ### Lifecycle examples) just after the intro, before Syntax.
And add an ## Examples just before ### Lifecycle examples
Co-authored-by: florent-leborgne <[email protected]>
Preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/1325/syntax/applies
Update applies_to page to match new versioning guidelines. Removed outdated parts and added missing info.