Rules/Recommendations for a Glossary/Terminology

[tomschr]

A glossary (or glossary list) is a part in our documents that defines unknown, ambiguous, or overloaded terms. However, this is not clearly defined in our styleguide nor do we have some good recommendations.

It would be nice if we could have a set of common rules. I would propose:

• length of the definition; as short and correct as possible. Rule of thumb: not more than 3 sentences.
• accuracy, how vage or how broad a term should cover a topic? (probably hard to "measure")
• references to other terms (1), what other terms should be referenced or included? How? Should it be referenced with glosssee/glossseealso or inside the definition with xref? When should we use one or the other?
• references to other terms (2) has to use glosssee or glossseealso. glosssee is mostly used for synonyms (Link, see soft link) whereas glossseealso is used as some related terms (link, see also file system). glossseealso references should be sorted alphabetically.
• references to other sections should be avoided IMHO. As there is probably no dedicated section for it or it is spread throughout all books, it is probably hard to pinpoint it.
• elements inside a definition we should only use para and maybe some inline markup, but no block elements
• overall structure should we group terms into glossdiv for higher ordering?
• Structure of the definition: the definition should not start with the term itself

[dariavladykina]

Some guidelines could be added to "Glossary" under Outline of a manual > Books.

[dariavladykina]

Right now, Virtualization Guide, Storage Guide and Security (Apparmor) + Security (Kerberos), have glossaries. There are also numerous sections in various books called 'Terminology'.
Only Virtualization Guide uses the 'proper' glossary tags and elements BUT it also features a 'Terminology' section for libvirt just as a variablelist. Visually, the difference in tagging is 0.

Question: do we want this instruction? Use lowercase for the term unless it is a proper noun
See screenshots:

[jfaltenbacher]

for the sake of automatic alphabetical ordering for the translations, please advise to use glosslist and define glossary.sort as 1, this will sort any glossary or glosslist in alphabetical order

[dariavladykina]

Closing this as the changes have been merged.