glossary directive

[Mpdreamz]

Glossary

Kind	Link
Reference	https://mystmd.org/guide/directives#directive-glossary
Documentation	https://mystmd.org/guide/glossaries-and-terms

Implementation

• Parses directives and aliases
• Emits HTML
• Unit tests
• Validation (emits, warnings and errors).

Specification compliance:

• Arguments is parsed and required
• Body defines terms

[KOTungseth]

In-flight PR for automatically generated definition lists from YAML: kibana/pull/191787

I'm also including my own notes ⬇️

Purpose

Clarify technical terms: Definitions explain specialized, technical, or domain-specific terms that may not be familiar to all users. This helps bridge the gap between experts and less-experienced users, ensuring clarity and understanding.

Ensure consistency: Providing clear definitions ensures that terms are used consistently throughout the documentation, which reduces confusion and misinterpretation. This is especially important in technical documentation, where precision matters.

Support learning: Definitions support the learning process by introducing new or complex concepts in a clear, concise manner. They help users build a foundational understanding of the technology, process, or system being documented.

Enhance usability: By defining key terms directly in the documentation (e.g., through tooltips, glossaries, or inline explanations), users don’t have to leave the document to search for meanings, making the content more user-friendly and efficient.

Facilitate global understanding: Definitions help ensure that a wide range of users, including those from different technical backgrounds or language levels, can fully comprehend the material.

Reduce ambiguity: Definitions remove potential ambiguity, especially in cases where the same term might have different meanings in various contexts. They provide specific, context-driven explanations.

Best practices

Organize definitions logically: Group related definitions together in a logical order. This can be alphabetical, thematic, or based on usage within the documentation, making it easier for users to find what they need.

Include examples: Whenever possible, provide examples of how the term is used in context. This can help clarify the meaning and show practical applications of the defined term.

Avoid overloading definitions: Limit the number of definitions provided in a single section. Overloading users with too many terms at once can lead to confusion and hinder understanding.

[Mpdreamz]

Ahh that's a great resource @KOTungseth I was thinking of exposing that under our own custom directive e.g

```{settings} path/to/settings.yml
```

This glossary is as followed:

:::{glossary}
MyST
: An amazing markup language that supports glossaries
:::

You can use {term}`MyST` to create glossaries.

Where you can define definitions/abbreviations and refer to them later on with the {term}\TERM` role which would create a popover explanation.

Ideally we support this separately (if we want it at all) by including all availableterms for a dockset in dockset.yml

And use {settings} for the well understood format of rendering of externally provided/generated settings/properties?

[KOTungseth]

Let's dedicate the glossary directive to Elastic Glossary.