Potpourri of my last thoughts and searches about that glossary, initially published on T129088#2776731.

Definition lists

Definition lists on HTML are implemented on MediaWiki.

A structure like

;Defined term
:Definition

is parsed as

<dl>
<dt>Defined term</dt>
<dd>Definition</dd>
</dl>

That's cool and accessible.

Synonyms

All documents say the same thing:

;Defined term
;Synonym at same level
:Definition

But there is no visual distinction between a preferred term and a synonym.
The best we can do is to add a note (example) but that's not the best option we can have. Plus, we don't know if it is accessible?

English Wikipedia manual of style advise to add an "also" line in the definition:

;Defined term
:also known as Synonym
:Definition

The also known would have a different styling that will feat to most of our readers, the "also known as" would be bonus for the accessibility. I think that's the best we can do.

Language specific synonyms

I think the synonyms translations should be open to translations. Translate some terms from English to an other language are not always accurate, plus some communities may have created a specific term for a specific feature. That's good because it shows that the product is adopted by communities.

The idea would be to have the translation of the synonyms remaining open. That way, people will not have to translate the English terms but will have a space where they can add the terms used in their language. This will systematically be documented on the qqq documentation language.

Template or not template?

That's the question.
That would help, but it may complicate the translations marking. Plus, templates are not always friendly with RTL & LTR. Based on that, the only template we can have will style the synonyms.

To do

• Create a page to document how to create glossaries the best way
• Create a template for qqq, to tell translators that they have to adapt the synonyms