Create a glossary for commonly used terms

[alyssadai]

We should have one place where we explain what the following terms mean in the context of Neurobagel:

• [ ] Metadata
• [x] Tabular or phenotypic data
• [x] Graph / database
• [x] Controlled term
• [x] Annotation
• [x] Node vs. federation API
• [x] Aggregate vs. disaggregated results

We also struggle with using synonyms or terms interchangeably to mean the same thing:

• Data model, data dictionary, schema
• Category, variable, common data element, attribute
• Category and categorical or continuous columns in a .tsv
• Controlled vocabulary, ontology

Tasks:

• [x] check out https://squidfunk.github.io/mkdocs-material/reference/lists/#using-definition-lists to see if this could help with a glossary
• [x] See also https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary
• [x] Start a glossary for the terms listed above
• [x] provide a recommendation for how we can link to the glossary terms from the docs where the terms are used (e.g. linking to the "Data Model" glossary page from everywhere we mention that word)

[surchs]

see https://bids-specification.readthedocs.io/en/stable/glossary.html for inspiration

[github-actions[bot]]

We want to keep our issues up to date and active. This issue hasn't seen any activity in the last 30 days. We have applied the _flag:stale label to indicate that this issue should be reviewed again. When you review, please reread the spec and then apply one of these three options:

• prioritize: apply the flag:schedule label to suggest moving this issue into the backlog now
• close: if the issue is no longer relevant, explain why (give others a chance to reply) and then close.
• archive: sometimes an issue has important information or ideas but we won't work on it soon. In this case apply the someday label to show that this won't be prioritized. The stalebot will ignore issues with this label in the future. Use sparingly!

[surchs]

@Remi-Gau do you have some advice for how we could get such a nice glossary as BIDS has?

[Remi-Gau]

The bids glossary is rendered from the schema. So feels like this approach is an overkill for neurobagel at this stage, no?

[surchs]

https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary is cool, but I don't think we want to do that because it will create a tooltip for the glossary term every single time it is used. So it gets pretty spammy. With the changes proposed in #138 we can create links manually - less fancy, but probably better.

[surchs]

Change of plan: we're discussing the terms in a GDoc and take the outcome of that to update the PR https://docs.google.com/document/d/1iC9fPzrT3499NrHIIYEFJJ1ulEnss5mscsvnB57xELY/edit?usp=sharing

Until then this is blocked.