search

openml / openml-python

Python module to interface with OpenML
https://openml.github.io/openml-python/main/
Other
278 stars 143 forks source link

Improve contribution guidelines #611

Open mfeurer opened 5 years ago

mfeurer commented 5 years ago

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

MichaelMMeskhi commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

PGijsbers commented 5 years ago

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 commented 5 years ago

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

PGijsbers commented 5 years ago

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

For each example;

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 commented 5 years ago

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:

MichaelMMeskhi commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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.