Improve contribution guidelines

[mfeurer]

Improve the contribution guide by adding a note in the readme. Also check for other places where beginners guides could be placed.

[MichaelMMeskhi]

I might start helping out on the tutorials side, definitely will take a look at this. I have heard personally from a lot of people that they don't know where to start. Making OpenML look "complex".

[mfeurer]

That would be great. I'd be happy to answer any questions on this and help where possible.

CC @PGijsbers who is currently redesigning the examples to make sure that there's no duplicate work (although I'm pretty sure that those two things are orthogonal to each other).

[MichaelMMeskhi]

@mfeurer Sounds good. I will get on this, this weekend. Will update you and @PGijsbers

[PGijsbers]

Much appreciated! I will work on improving and expanding the examples this week. You should be able to go through them and see what is missing or unclear, and continue from there :)

[MichaelMMeskhi]

@PGijsbers should we somehow discuss the whole structure of tutorials/examples and contribution rules?

[PGijsbers]

I am not sure what you had in mind?
I think we should aim to have:

• examples involving basic functionality of each concept: dataset, task, run, flow, suite, study.
• more interesting examples with more powerful use cases: e.g. automatically running a benchmark, re instantiating models.

For each example;

• if they upload anything, use the test server and make a warning note that we are using the test server so as to not pollute the live server.
• if they don't, use the live server.

I am personally not in love with the gallery overview as (at least right now) it seems difficult to see what each tutorial offers (you have to mouse-over for a description). Perhaps there are better alternatives there, but I don't know how @mfeurer and @janvanrijn think about that.

[mfeurer]

There are basically two ways the examples are listed:

1. In the user guide: https://openml.github.io/openml-python/master/usage.html (although not all are there yet)
2. In the example gallery: https://openml.github.io/openml-python/master/examples/index.html

The reasoning is to reduce the effort for writing and keeping docs up-to-date until the package is developed further or there are more contributors.

I'd be happy about anything that helps, especially a guide on how to get started which is linked from:

• README.md
• the docs
• the issue tracker template
• the pull request template

[MichaelMMeskhi]

@mfeurer Okay. I looked over the two links you provided. So you want to update the information there? I can start off with analyzing README.md files and fixing/adding new information. Then head over to the docs and work on introductory pages and so on... What do you think? The docs are O.K. for experienced researchers but not for industry people because they don't know what's going on. I have had two math professors ask me about OpenML but they never "understood" the real purpose behind it.

@PGijsbers One other thing. Standardization. Let's come up with a template that README.md's will follow and so on for other documents. To keep things clean and clear. I can provide some examples and we can decide which one fits more.

[mfeurer]

I can start off with analyzing README.md files and fixing/adding new information. Then head over to the docs and work on introductory pages and so on... What do you think?

That would be great. It's probably best if you branch off from update_examples which is PR #684.

I have had two math professors ask me about OpenML but they never "understood" the real purpose behind it.

That's unfortunate. Any suggestions on how we can fix this besides updating the python docs are appreciated.

[MichaelMMeskhi]

I can start off with analyzing README.md files and fixing/adding new information. Then head over to the docs and work on introductory pages and so on... What do you think?

That would be great. It's probably best if you branch off from update_examples which is PR #684.

Sounds good. Will start that on Saturday.

I have had two math professors ask me about OpenML but they never "understood" the real purpose behind it.

That's unfortunate. Any suggestions on how we can fix this besides updating the python docs are appreciated.

For example, look at Google AutoML front page. They have illustrations and simple descriptions of what they offer. It gives non-experts or new comers better info of whats going on. I suppose something like this can help.

[mfeurer]

Sounds good. Will start that on Saturday.

Cool, I'm looking forward to see the outcomes.

For example, look at Google AutoML front page.

I'm not sure if it is easy enough to see, but if you scroll down on the front page, there's quite some introductory information. If you have any suggestions on that, I'm sure @joaquinvanschoren will be happy to hear.

[MichaelMMeskhi]

@mfeurer @PGijsbers One more thing that came to my mind. I saw you updated the examples. These are all .py files. Would you agree that if instead we uploaded .ipynb files so new users could have a better look at how the code works with outputs also shown? I can create a intro example in notebook format and if you want take a look at it to see how it looks.

I am afraid I might mess something up when trying to merge my changes to update_examples so for the meantime, heres my forked version.

[mfeurer]

We deliberately moved from notebooks to python files recently because they are easier to render in the documentation and also easier to unit test. sphinx-gallery converts those python files both to the example and notebooks, and can actually download the notebooks from the bottom of the respective examples, for example the introductory example.

[joaquinvanschoren]

I added a link to the tutorial on github.com/openml/openml-tutorial where there is a complete notebook with the main API functions. It also includes a button to launch it on MyBinder and Colab.

[MichaelMMeskhi]

I added a link to the tutorial on github.com/openml/openml-tutorial where there is a complete notebook with the main API functions. It also includes a button to launch it on MyBinder and Colab.

Yeah I've seen that website. I see there are intro and documentation resources but are more or less scattered around. Anyway, I will slowly do my part and try to contribute in fixing and improving all of this.