[docs] Add more guidance on products metadata

[colleenmcginnis]

Fixes #1818

Adds more guidance on products metadata. I left a couple code comments inline where I'm not sure what we want to recommend.

[github-actions]

🔍 Preview links for changed docs

• docs/configure/content-set/navigation.md
• docs/syntax/frontmatter.md

[theletterf]

Thanks! Some suggestions and comments as a recent products user.

[theletterf]

Where's the mapping defined? Shall we point to the source code?

[cotti]

@theletterf At this moment on main, it's in the code - I'm working on a change that will migrate this to a separate file. I'll update the documentation accordingly by the time the PR is up.

[colleenmcginnis]

Oh, I was just expecting the reader to look at the table in the dropdown. Maybe we should make that clearer?

[theletterf]

Could we perhaps replace this with a small table of When to use vs When not to use?

[reakaleek]

This makes sense.

But the original reason was that products are only used for the search.elastic.co filters. At the time of implementation, we did not know how applies_to and products relate to.

Not sure if we even know this today. (this statement is actually a good explanation) But yes, there were ongoing discussions that they are similar. same same but different.

[colleenmcginnis]

What do you think about this guidance @elastic/docs-tech-leads?

Could we perhaps replace this with a small table of When to use vs When not to use?

Can you be more specific about what the table would include? General guidelines? Multiple examples? Something else?

[theletterf]

@colleenmcginnis Examples, I would say. Just a suggestion though, this is not blocking the PR.

[florent-leborgne]

This is a tricky example. I would add the corresponding product(s) in all cases.

Meaning that "A page with content that applies to Elastic Cloud Serverless should also be identified with the "cloud-serverless" product ID", to be searchable as such using the elastic.co search. I think this is true in most cases. If the content applies to "Stack", then you'd want product ids to identify which stack components are relevant here, etc.

[lcawl]

Meaning that "A page with content that applies to Elastic Cloud Serverless should also be identified with the "cloud-serverless" product ID", to be searchable as such using the elastic.co search.

In that case wouldn't we want that to be derived automatically from the applies_to at some point, rather than requiring the duplication? Then the products would only need to include the level of product detail (components of the stack, etc) that aren't covered in the other metadata

[colleenmcginnis]

I would add the corresponding product(s) in all cases.

This would require revisiting the products metadata all pages across all repos to duplicate what's included in applies_to since that was not the guidance we used when first adding products. I'm not sure if it's worth the effort without really knowing how we want to use this metadata going forward. @KOTungseth thoughts?

It would probably also mean that filtering by search results by Elastic Cloud Serverless might not be that helpful on its own since so many pages include serverless/stateful applies_to. For example, the PRs that sparked this PR were adding cloud-serverless to (almost) all APM agent docs pages.

[florent-leborgne]

In that case wouldn't we want that to be derived automatically from the applies_to at some point

IMO, yes, except for "Stack" where the corresponding product IDs are more granular: elasticsearch, kibana, etc.

[florent-leborgne]

But overall this seems logical, if we mark content as applicable to a context, why wouldn't we allow users to find that content when selecting that context through facets?

[florent-leborgne]

This would require revisiting the products metadata all pages across all repos to duplicate what's included in applies_to since that was not the guidance we used when first adding products. I'm not sure if it's worth the effort without really knowing how we want to use this metadata going forward.

I agree, and I think we shouldn't change this logic before the next phase of thinking around applies_to and versioning. For now we should "just" make sure that the way we specify products ids leads to a better search experience

[florent-leborgne]

This is a tricky example. I would add the corresponding product(s) in all cases.

Meaning that "A page with content that applies to Elastic Cloud Serverless should also be identified with the "cloud-serverless" product ID", to be searchable as such using the elastic.co search. I think this is true in most cases. If the content applies to "Stack", then you'd want product ids to identify which stack components are relevant here, etc.