Create glossary of OpenSAFELY-related terms

[StevenMaude]

Background

Some terms used in an OpenSAFELY context may have overloaded meanings. For example: "job", "project", "workspace". It's important that readers understand the specific meaning of these terms: it helps them make sense of the text, and, from that, better understand OpenSAFELY. As @sebbacon mentions below, this is also important for developers, as well as users, trying to understand the system too.

The current situation

As in #1, an initial glossary added began by referring only to OpenSAFELY-specific terms. It then expanded to non-OpenSAFELY healthcare terms and abbreviations.

I'll term this existing glossary as the "word hover" glossary, as in the documentation, you get definitions on hover. Example of this from the current documentation:

Questions

Which OpenSAFELY terms should be defined? And what are the definitions of those terms?

This requires discussion among OpenSAFELY developers aware of the key concepts. It is worth reviewing an initial draft with users who may be aware of terms that haven't been listed, or where proposed explanations could be made easier to follow.

How should the glossary — or glossaries — be organised?

Because of this current "word hover" glossary, it's not immediately obvious what would be the most useful structure.

• This new OpenSAFELY glossary might be useful to have available as a single page within the documentation. That's as compared with the current "word highlighting" glossary that is sprinkled throughout the documentation.
• Some OpenSAFELY terms are already in the "word highlight" glossary, so there's the possibility of overlap.
  • Not sure that there's a simple, supported way by Material for MkDocs to facilitate reuse of glossary terms. I couldn't find anything from a quick look. If we included terms in two places, then we might want to ensure the same definitions are used.
  • However, there's also a case for having a concise hover definition for quick reference, and a separate, longer exposition for explanation of the concept. (In practice, it seems unlikely that the OpenSAFELY term definitions are likely to change much once those concepts are established.)

Options for organising glossary terms

These are the possible options I can think of; happy to hear proposals others may have too :thought_balloon:

1. Create a separate glossary reference page (non-hover) for OpenSAFELY terms only. Use "word hover" glossary for generic healthcare terms, removing any OpenSAFELY terms from "word hover".
2. Create a separate glossary reference page (non-hover) for OpenSAFELY terms only. Use "word hover" glossary for generic healthcare terms and concise definitions of OpenSAFELY terms.
3. Create a separate glossary reference page (non-hover) that covers all terms, OpenSAFELY and generic healthcare. These definitions are exactly the same in the "word hover" glossary. Not yet sure how best to implement this.
4. Remove the "word hover" glossary entirely and just have a single glossary reference page that covers all terms, generic healthcare and OpenSAFELY.