elastic / elastic/docs-builder

[docs] Improve docs on using `products` metadata

Open
#1,818 7 comments 2 reactions 0 assignees View on GitHub
ai-triaged ai:writer-question documentation stale
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

While reviewing https://github.com/elastic/apm-agent-dotnet/pull/2650, I realized how little information we have in the docs-builder docs about how to use `products` metadata.

In addition to the [list on the frontmatter docs page](https://elastic.github.io/docs-builder/syntax/frontmatter/#products), we should also add:

* Documentation on using products in `docset.yml` to apply metadata to every page in a doc set.
* Guidelines on how to choose which `products` to include. Some factors to consider:
* Think about how users will use this data via search[^1] (for example, if a user was searching for information on Elastic Cloud Serverless and filters to pages that are tagged with `cloud-serverless`, does it make sense to include a page from the APM .NET agent docs?).
* Avoid just duplicating information in `applies_to` (for example, just because a page describes functionality that is applicable to a specific deployment method doesn't mean the page is _about_ that deployment method).
* Anything else?

[^1]: Note: I'm not sure if `products` are going to be used differently in the new search experience that's being developed. @KOTungseth and @reakaleek might be able to clarify.

cc @theletterf

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.