Synchronize terminology documentation

[javh]

We need to sync up the various terminology sets:

1. AIRR-C Terminology document (internal link)
2. AIRR-C Glossary of Terms: https://zenodo.org/record/5095381#.YTJK7NNKjgE
3. docs/appendix/terms.rst: https://docs.airr-community.org/en/stable/appendix/terms.html

The Zenodo link will be authoritative, but the AIRR Standards docs should be consistent.

[schristley]

It might be nice if the AIRR docs auto-created the document that was put up on Zenodo? That would be one way to insure consistency, by generating from a single source file.

[javh]

Good idea... Maybe if the Zenodo record has an .rst version. Not sure I'm ambitious enough to parse the .docx to .rst on the fly (though, I suppose it's feasible).

[scharch]

Where's the internal Terminology document?

[bussec]

Where's the internal Terminology document?

Here: https://docs.google.com/document/d/1YMOTIJFjOW85ZB__7LcaWQDzSSjlHBo3-irAVu2kgoY

Is there a special reason why the document on Zenodo is a DOCX instead of a PDF?

[scharch]

I don't think so. I will work on this in October.

[scharch]

This is insanely kludgy, but we could split off the terminology into its own repo... Then the main docs can incorporate by reference and we can set up integration so that Zenodo automatically archives each new release of the terminology repo.

The better answer is probably just to have docs/appendix/terms.rst be the version of record and manually update Zenodo to match as necessary. I don't think we need a separate internal document; if we want some terms to be restricted we can add them to the appendix/glossary and that should be sufficient.

thoughts?

[bussec]

The Terminology document has now been updated, please have a look. In addition, I will try to come up with a consolidated document containing all terms from all sources.

[bussec]

@scharch @javh @GreiffLab

As discussed above, I moved the content from the Google Sheets that we used to consolidate the three documents mentioned above and the Restricted Terms document into a single (non-tabular) RST file in a separate repo on Github:

https://github.com/airr-community/airr-terminology/blob/main/airr-community-terminology.rst

The repo has Github Actions enabled and will compile the RST into a PDF using Sphinx. Once compiled, the PDF is then automatically uploaded to Zenodo and will update the record below (note that this is Zenodo's "sandbox" instance, but it runs the same software as their main site (zenodo.org), so we would just need to change two lines in the config if we want to put this into production):

https://sandbox.zenodo.org/record/1066299

There are or course still a couple of things to do, e.g.,

• fine-tune the LaTeX-compilation that Sphinx uses to create the PDF, so that the document becomes less of an eyesore,
• add some safe-guards to the uploader and
• define a workflow how the document would be updated.

Any comment or feedback is welcome!

[scharch]

Looks good!

I imagine that

• define a workflow how the document would be updated.

is going to have to eventually be added to the governance document as a formal mechanism, no?

[bussec]

@scharch Yes. There are IMO two aspects here:

• The most critical point will be the "Definitions - AIRR Community" subsection, as this contains text from a normative section ("Definitions") of the Governance, so we would need a workflow here that goes through a community vote.
• All the other parts could be updated more easily by the WGs, e.g. when they send a manuscript for endorsement, but also this should undergo some review.

[javh]

Very nice! That solves a lot of problems.

[javh]

Reminding myself to fix this PR: https://github.com/airr-community/airr-terminology/actions/runs/10765195815/job/29849108300?pr=1