Create a reference "Essential Ontology Curator Toolbox"

[matentzn]

I would like to suggest to create a single page which provides

1. A list of essential tools for all Ontology curators to have installed
2. Some basic instruction to install these

We created something similar for Semantic Engineers in general: https://oboacademy.github.io/obook/reference/semantic-engineering-toolbox/, but I would propose something more focused, more "essential", that curators can take to their IT departments and say: this is what we need when we get our new machine.

We should also make sure that this list makes the curators LLM ready, and avoid them being thrust in the abyss of python environments.

Here is my suggestion to start with, other ideas welcome:

1. docker (and ODK): this is the most important as everything else can be delivered this way; we need to ensure IT departments do not block this part.
2. make
3. homebrew
4. python version 3.11 (for now) and pyenv, pipx
5. In the global python environment
   • oak
   • ontogpt
     6. Protégé
     7. Visual Studio Code (default) or similar (by preference of curator)
   • Should be able to edit and run jupyter notebooks
   • Should be able to permit seemless textfile editing with regex search and replace workflows
   • Should (optionally) support some co-pilot like infrastrcture
     8. Slack (for communication)
     9. GitHub Desktop (always)
     10. Zoom
     11. Teams (yiiiikes, but necessary for some collaborations)

Anything missing?

[matentzn]

@joeflack4 suggests to add a lightweight texteditor into the mix, like "sublime". Probably not a bad idea, although whatever you can do with sublime you can do with VS Code, so there is some level of duplication when it comes to training people.

[gouttegd]

One remark about this bit:

3. homebrew

Some workplace may have an existing policy that mandates the use of a specific package manager, and this recommendation may run afoul of such a policy if the specific package manager is not HomeBrew.

For example, FlyBase-Cambridge has a policy of mandating the use of HomeBrew. So of course that’s fine because it happens to match to recommendation, but if the policy had been to use MacPorts instead, that would leave the users torn between the policies of their IT department and the recommendations from the OBook – not great.

So I’d suggest that we simply recommend the use of a package manager, without specifically insisting on HomeBrew.

[caufieldjh]

Seconding re: package managers. Not a pressing issue for Linux flavors as the package manager is what most folks will be using anyway, but it's helpful to say "install these with your package manager instead of running a binary directly" etc. And for Windows, Chocolatey works well.

[matentzn]

I agree with both of you; here is my reasoning for documenting a default:

In my experience the chaos of package managers and ways to install python and CLI tools want to promote is a complication that significantly deters non-technical people picking up our tools.

I recently checked with 5 of our curators, members of our community for many years, and none even had python installed. Therefore I would like to document 1 way to do things, and if we hit an organisational wall, document a second, rather than leaving this complex area up to the curators to figure out.. What do you think?

[caufieldjh]

That's fair, and aligns well with the first item in your list re: Docker and minimizing potential obstacles.

[gouttegd]

Therefore I would like to document 1 way to do things, and if we hit an organisational wall, document a second, rather than leaving this complex area up to the curators to figure out.. What do you think?

Two documents will never be enough. We’re never going to be able to cover the diversity of situations:

• Which operating system? You’re obviously assuming macOS in your initial message, that’s a pretty bold assumption. Sure, many of us may be using macOS (sometimes against our will), but we know there are also Windows and GNU/Linux users.
• Which version of that operating system? What works on one version may not work on another.
• Does the user have admin rights on their machine? Or must any software be installed by an IT guy?

Also, I can very well imagine a situation where installing any kind of package manager (be it HomeBrew, MacPorts, Chocolatey on Windows, NIX, etc.) would be forbidden entirely by the IT department, on the grounds that such software is intended to allow users to install whatever they want and the point of the IT policy is precisely not to allow users to install whatever they want.

So, what I would do instead:

• First, provide merely a list of what software must be installed, without any mention of how they are (or must be) installed. So, no mention of a package manager: the package manager is part of the how, not the what. For Python, we just say that users must have a specific version of Python, and that they must be able to either (1) install Python packages in their per-user site-packages directory, or (2) create virtual environments where they can install packages (so they must have venv or any other similar tool).

That list is the actual requirements, that is applicable to all systems, all versions, all situations. It basically would say, “you must somehow get those pieces of software, no matter how – if you’re working in a constrained environment where all software must be installed by the IT staff, give them that list and let them handle it”.

• Then, we can (try to) provide one or several howtos on how to implement the requirements. At the very least one document for the “ideal” situation where the user is admin on their machine and can do whatever they want (there we can recommend the use of one specific package manager).

And then over time, we grow that list of howtos to cover more and more situations as we run across them. Possibly by asking users to contribute feedback (“hey, you just finished setting up your Windows machine? Everything works? Fantastic! Care to write up some notes on what you did exactly, for the benefit of the next Windows user?”).

[sierra-moxon]

100% love this effort, and it is essential! I am listening here as someone trying to construct a reasonable development setup for training users on making LinkML models.

I also wanted to mention pipx -- as a begrudging convert (there are too many ways to do this), it, in combination with pyenv, does help simplify the python environment run-around.

Agreeing with everyone here, that this doc needs two sections, the what and the how, For OS, I was going to write that xcode might be a way to go here (we get git, make, and a lightweight text editor with that bundle).

....Alas, perhaps the only tool we need to tell people about is a $20/month ChatGPT subscription :)

[matentzn]

@sierra-moxon thank you for your input! I myself have not used pipx yet, but will look into it! Added it to the list!