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.

[sebbacon]

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.

Yes. However, there's also a second audience who at this stage is at least as important: the developers, who need precise terms and definitions to help them reason about the system efficiently.

Options for organising glossary terms

I prefer a version of option (2): create a separate glossary reference page for opensafely and include this both in the "hover" glossary and in its own standalone page.

mkdocs does have the capability to include snippets (which is how the hover-behaviour is applied to each page); is there a reason this wouldn't do the trick?

[StevenMaude]

mkdocs does have the capability to include snippets (which is how the hover-behaviour is applied to each page); is there a reason this wouldn't do the trick?

Including the current glossary.md as a page in the documentation results in an empty page. (Some Markdown parsers do process the glossary.md into at least some difficult-to-read HTML; e.g. GitHub.) This is reproducible even if you create a simple new page that contains just one simple entry.

So I think a processing step is needed before build. This step would add the OpenSAFELY glossary page terms to the "word hover" glossary, such that all the OpenSAFELY glossary terms are in the correct Markdown format expected by the abbreviations extension that produces this existing glossary. there: *[example term]: some definition

What you'd need for the new glossary page is maybe something like * **example term**: some definition.

But from the snippets documentation:

This is meant for simple file inclusion, it has no intention to implement features from complex template systems.

So if we do this, this would probably be a simple plugin unless there's an existing plugin for this task.