[Do not merge] [E&A] Add applies frontmatter to most explore and analyze files

[florent-leborgne]

[This PR will evolve - it's not a proposal]

For now this is a place for discussion and ideas on options we have to call out content applicability at:

• the page level
• the section level
• the paragraph/line level
• inline

Most likely dimensions to call out are:

• Environment type (ECE, Elastic Cloud {incl. Cloud Hosted and Serverless}, Self-managed)
• UI/stack version (Serverless, Stack 9.x, Stack 9.y, ...)
• product/feature lifecycle stage (tech preview, beta, ga, deprecated, removed)

Observations:

• These docs are for stack 9+, ECE 4.0+. The applies frontmatter needs to provide a way to indicate this instead of a single version. For instance, stack: ga "From 9.0.0"
• Features can be at different lifecycle stages depending on their environment. What is the best place to communicate this? Is the "this content applies to" badge a good place? Not very elaborate example in Explore and Analyze > Discover > Search sessions
• Features can differ from one version to another, or between stack and serverless. Sometimes it's just a setting or two, sometimes there are tiny implications in multiple places, which can make a page harder to read, and could also make one deployment option some kind of outlier, which is probably counter-productive at some levels. Tabs or breaking pages into 2 pages seem better in terms of readability and clarity than inline notes or callouts. See some options under Deploy and Manage > Manage spaces

[shainaraskas]

These docs are for stack 9+, ECE 4.0+. The applies frontmatter needs to provide a way to indicate this instead of a single version. For instance, stack: ga "From 9.0.0"

I question whether this is needed. I'm hoping we end up with some sort of banner saying "these docs are 9.x+, ECE 4.x+"

We might want to add a 9.x indicator on features we know are new in 9.x but I don't think it needs to be everywhere if we get that banner. We might also consider having an "about these docs" page that makes is clear what the badges mean and what the "default" or "empty" state means.

[florent-leborgne]

@shainaraskas good points. That could be way better than what I proposed there, especially on the long term when 7.x and 8.x are ancient history (though it could take a bit of time). As long as we make it obvious to any reader that what they're reading doesn't apply to pre-9.0, I'm good with it

[lcawl]

In a serverless project, you must have an admin role on that project to manage its Spaces.

Do we need to have this in an admonition? This seems unnecessarily eye-catching to me.

[shainaraskas]

I agree with Lisa. wonder if we could do something like this:

* Serverless projects: **Admin** or equivalent
* <Some word that means all but serverless>: `kibana_admin` or equivalent

[lcawl]

In a serverless project, the number of spaces is limited to 100.

This is another one that I don't think merits an admonition. But if we do go down this path as far as a best practice we'll want to give advice on what warrants admonitions in general.

[shainaraskas]

+1

The maximum number of spaces that you can have differs by deployment type: 

* Serverless: Maximum of 100 spaces
* <Some word that means all but serverless>: Controlled by the [`xpack.spaces.maxSpaces`](https://www.elastic.co/guide/en/kibana/current/spaces-settings-kb.html) setting. Default is 1000.

[lcawl]

Thanks for drafting these examples! My preference is for deploy-manage/manage-spaces.md (with less admonitions) but will play with more examples tomorrow too.

[leemthompo]

I like the tabs for when there's anything more than a handful of differences, it feels a lot cleaner and easier to parse as a reader.

My only concern would be that hand-building tabs is not scaleable, so I'd want a compact syntax in the source (yaml if possible), which the build system transforms into the appropriate presentation. Whatever approach we decide on, I'd push very strongly for separating form and content in this way, so that we can make changes to how stuff is presented going forward by fixing it in the CSS/build system, rather than having to edit the source pages. That way if we decide tabs don't scale past a certain point, we don't have a lot of manual debt to repay down the line.

Two other opinions:

• I agree that having one "normal" path, and an admonition for serverless isn't viable
• But I also don't think version/deployment type callouts in plain prose (i.e. without differentiated formatting) work if there's more than a handful of instances on a page.
  • i.e. I'd advocate strongly for visual differentiation

[florent-leborgne]

My preference is for deploy-manage/manage-spaces.md (with less admonitions)

I think this could work well when there are less than a handful targeted differences on the page, but it won't scale well over time in such instructional content. Already for this example, I find it hard to read, especially for a serverless user, with too much content that the reader has to process while it doesn't even apply to them.

[shainaraskas]

I'd consider pulling this out of a note as well

Serverless project types: [![Elasticsearch](../images/serverless-es-badge.svg "")](/solutions/search.md) [![Security](../images/serverless-sec-badge.svg "")](/solutions/security/elastic-security-serverless.md)

[florent-leborgne]

yep I think we all agree that using notes for version/deployment type differences isn't a great way to show it

[shainaraskas]

to everyone in this thread looking at the versioning strategy: I've moved the examples to a new, smaller PR so they can be previewed using the auto build

#355

[florent-leborgne]

This was for testing, closing