Improve inline applies_to documentation

[theletterf]

Current inline applies_to documentation lacks examples of the following:

• Adding product lifecycles and versions. For example:

{applies_to}`edot_python: preview 1.7.0`

• Adding more than one lifecycle state/version in the same statement. For example:

{applies_to}`{ serverless: "ga" , stack: "ga 9.1.0" }`

[colleenmcginnis]

I think there are two different tasks captured here.

Syntax reference
One is to have more complete syntax reference documentation in Syntax guide > Applies to. In my opinion, the information on this page should be objective — purely what the syntax looks like (as opposed to the best practices and more contextual/subjective information included in Write cumulative documentation).

I think we can update the syntax reference now to make it clear that:

• When using a subitem within product or deployment in an inline annotation, you use the key of the subitem (e.g. edot_python: or ece:) without reference to product or deployment (e.g. not product.edot_python: and not product: edot_python:).
• When you need to include multiple lifecycle/versions for the same key in an inline annotation (e.g. labeling a feature that was in beta in 9.0.0 and in GA in 9.1.0), include all the lifecycle/versions in a single inline {applies_to} (e.g. {applies_to}`stack: ga 9.1.0, beta 9.0.0`) so we can take advantage of auto-sorting versions.

Cumulative documentation
The other is to make a decision about how we want to handle when there are multiple keys (products, deployments, stack/serverless). There are a few factors that should go into that decision:

• How important is it that products/deployments/stack/serverless in inline annotations are in a consistent order like we assert in page- and section-level annotations in addition to sorting by version within a single key?
• Is the benefit to the reader great enough to justify making the contributor experience a little more complicated (i.e. needing to format as a JSON object like {applies_to}`{ stack: "preview 9.1", product: { edot_python: "preview 1.4.0" } }`)?
• If we think forcing the order of annotations is important enough and we don't want to make contributors figure out how to format the information as JSON, could we use multiple inline {applies_to} directives and at build time check if there are adjacent inline {applies_to} directives and sort them before rendering them in a page?

Personally, I'm not convinced (yet) that the products/deployments/stack/serverless order matters enough to justify complicating the contributing process, but I'm curious if others feel strongly one way or the other.

cc @elastic/docs-tech-leads

[theletterf]

Personally, I'm not convinced (yet) that the products/deployments/stack/serverless order matters enough to justify complicating the contributing process, but I'm curious if others feel strongly one way or the other.

FWIW, I don't think the order matters so much, either. I see the inline applies_to badges as a mechanism that grants contributors freedom to place metadata anywhere on the docs: taking that freedom away sort of makes it less appealing.

[szabosteve]

++, the best would be to keep this as simple as possible. I'm not convinced either that enforcing a specific order is important enough to justify adding complexity to the contrib process. :twocents:

[shainaraskas]

I'm ok with keeping it simple for inline. was just overly excited to allow auto-ordering but it's probably an edge case, especially because we can specify multiple lifecycle states in the same key (where ordering is more important) using comma separation

[florent-leborgne]

IMO any ordering concern (multiple keys, or multiple values for a key) should be handled by the system and not be something that we should need guidelines for

[theletterf]

PR: #1793