De-duplicate glossaries across spec & otel.io

[svrnm]

What are you trying to achieve?

We discussed this in the past already: currently we have 2 glossaries, one on the website and one here in the spec repo. I think this is fine except when there is a duplication of terms (and worst case conflicting definitions), so it would be good if we can find a way to either only have one glossary, or keep them "in sync", i.e. the spec glossary is authorative, we merge it into the docs glossary and add additional terms there that we might not want to have in the spec because they are not relevant enough or to vague.

Additional context.

A solution I could imagine is the following:

• have a YAML file (?) in spec that is rendered to the glossary in the spec
• have another YAML file in docs
• In docs we "merge" those 2 and render it to a global glossary under https://opentelemetry.io/docs/concepts/glossary/

cc @open-telemetry/docs-approvers

cc @jpkrohling @danielgblanco @pellared as we discussed this during EU triage.

[chalin]

I'd rather stay away from YAML for docs or doc pieces. I'd vote for a markdown file with special formatting rules (e.g., a markdown file with only glossary entries, each beginning with a level 2 heading).

[svrnm]

I'd rather stay away from YAML for docs or doc pieces. I'd vote for a markdown file with special formatting rules (e.g., a markdown file with only glossary entries, each beginning with a level 2 heading).

That works as well, I think that's also what k8s is doing: https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary

[chalin]

Right, though I was thinking a single markdown file.

[svrnm]

Right, though I was thinking a single markdown file.

yes, that works as well 👍