Product tags

[reakaleek]

Context

Currently, docs-builder allows product tags to be defined in the docset.yml config or in frontmatter.

See the following examples:

• docset
• frontmatter

We implemented this feature ASAP to restore the search filtering capabilities which is still WIP in #1200.

Currently, if you configure the products attribute in the docset.yml config, it means every page within that docset will have this product as tag.

When you add it to a markdown page frontmatter within the same docset, the products of both docset.yml and frontmatter will be merged.

Questions

• Should the products from docset.yml and frontmatter be merged?
• Is there a necessity to override it instead of merge?
• Are there any other use cases that you can think of? (E.g. do you think this should be configured on a toc.yml level? to be able to set it for all the pages within a toc.yml)

Let me know your opinions. Thank you!

[theletterf]

I think override mechanisms aren't healthy. Duplicated information between docset and frontmatter should be ignored (count as one) and the rest should be merged. Searching and replacing IDs in docs is relatively easy.

[reakaleek]

Do you see a reason where a page or even a toc area might not want to have the docset product?

[theletterf]

I don't. If the page belongs to a docset, there will be something tying it to the products in the docset, even if marginal.

[colleenmcginnis]

Do you see a reason where a page or even a toc area might not want to have the docset product?

IMO If there is a case like this, then we shouldn't use the products option in docset.yml at all. All products should be defined at the page level (like in elastic/docs-content). The products option in docset.yml should be reserved for use cases where we want to apply a product to all pages.

[lcawl]

Are there any other use cases that you can think of? (E.g. do you think this should be configured on a toc.yml level? to be able to set it for all the pages within a toc.yml)

The only reason I can think of for doing this is to ensure consistency around how the pages in a particular subsection are tagged. For example, the pages under "Supplied configurations" and "Function reference" in the Reference > Data analysis section are all related to machine learning features. Currently it looks like each page is tagged with only the "ml" product tag (e.g. https://github.com/elastic/docs-content/blob/main/reference/data-analysis/machine-learning/machine-learning-functions.md). However, if it was decided that they should also be tagged with "elasticsearch", "kibana", or "elastic stack" product tags, then it would be nice to do that at the toc.yml level rather than on each page.

Side-note that if the list of products is what was given in #1200 (comment) then I personally find it unclear when/if we'd want folks to use general "products" like elastic-stack and how/if we want to layer the feature-specific "products" like ingest and machine-learning. I think we'd need to be really clear about how/when a feature becomes a "product" going forward (if we have any control over that list).

[reakaleek]

Thank you for the detailed feedback!

@colleenmcginnis would this example also apply to cloud?

[colleenmcginnis]

In my opinion having three levels where products can be defined (the whole doc set, sections within a doc set, and the page level) could get confusing to contributors, but I don't feel that strongly and it's probably @KOTungseth's call. (Just thinking back to how confusing it was as a new contributor in AsciiDoc when there were so many different ways to do the same thing. 🙃)

[reakaleek]

@lcawl what I'm concluding here is that we might want something like a feature tag additionally to products?

Do you think it makes sense to add it to the "Search Meta Tags" RFC?

[reakaleek]

@colleenmcginnis makes sense. If the current syntax is simple and achieves what we want to do. Then I'm happy to not change anything.

[lcawl]

@lcawl what I'm concluding here is that we might want something like a feature tag additionally to products? Do you think it makes sense to add it to the "Search Meta Tags" RFC?

Yes, if there continue to be a subset of features that are included in this metadata IMO they should be defined differently due to the way they span other products. I haven't participated in the RFC but am happy to do so if you ping me a link.