What should we NOT document?

[caro401]

anything about how to use kiara from jupyter? anything about how to use kiara via a (bash) CLI as an end user anything about how to use kiara from a python script as an end user

@makkus @MariellaCC does this match with your understanding?

[makkus]

I guess it is about priorites. I would recommend anyone creating modules/pipelines to use 'pure Python' and the cli, not jupyter -- it is really not the best tool for that, even if it is the technology most people around here are most comfortable in and I would prefer not having to support people who try to use jupyter for this, because it creates problems that would not exist without the stuff running inside jupyter. This is a team decision though, if anyone steps up and takes up support responsibility I don't mind per se. Without some meaningful work on class loading and packaging it's currently not possible to create a kiara module in a jupyter notebook.

Anyway, in that way, the cli should probably be at least somewhat documented. I'd think the getting started tutorial I wrote would be good enough for this purpose, with some additions about how to enable debugging and maybe some examples of what usually goes wrong. Documenting/supporting/encouraging the use of cli for end users is something that ideally we'd do, because it can be quite useful in some cases (batch/cron jobs, etc.). But again, it's a question of priorites and picking our battles, so I'd put that pretty far down the list personally.

Same with the use of kiara from python and jupyter, it's not something where I feel I can support users personally, and at this stage (kiara being developed with a tight focus on being used as a backend not a Python library) I would not recommend anyone pulling in a kiara dependency (with its unproven track record and fairly small dev resources compared to its scope) without a very good reason. I think I'm alone in this opinion though, so someone else should probably comment here and develop a strategy. That would probably involve gathering use-cases, user stories and scenarios we want to support for that kind of usage of kiara, and also determine who is responsible for this.

[MariellaCC]

@caro401 Based on the questionnaire results from last week and previous discussions, one of the entry points for our users would be Jupyter. CLI was considered a discouraging experience by several users. So, in my understanding, one of the priorities seems to be to document Kiara from Jupyter.

[caro401]

My bad for not keeping this issue up to date! There seemed to be some agreement from your questionnaire that we should indeed be documenting how to use kiara via its Python API (usually from the context of jupyter, but this isn't different from writing in a python script in terms of the content required)

The questionnaire responses seemed to really not like using the bash CLI, so we shouldn't focus efforts on documenting that for now.

If that matches with @MariellaCC's understanding, let's close this issue as outdated, and proceed in line with the results of your questionnaire, documenting the Python API for programming-aware end users, and not documenting the CLI since no one enjoys using it.

[MariellaCC]

@caro401 No problem at all, my bad for the late response, but I wanted to see what the questionnaire's results would indicate.

Yes, absolutely, agreed. I am using the opportunity of this comment to close it then as per your suggestion.