RFC Plan for reworking the tutorials

On top of the Examples and the User Guide, we have a Tutorial section. This part of the docs is quite old, and some of it became redundant with the UG and / or the examples. Lots of users will be drawn to the tutorials page at some point, so I feel like it’s important that we give it the attention it deserves, just as we do for the UG.

Here’s a proposal on how to deal with each section of the current Tutorial page:

1. An introduction to machine learning with scikit-learn: This is what used to be our “Quick Start” guide before it was re-written in https://github.com/scikit-learn/scikit-learn/pull/14920. I find this doc quite strange and unintuitive, because it deals with very different levels of expertise: it starts by introducing ML, and it ends up by detailing how to cast data to flaot64.

   I would suggest to completely remove this guide, or alternatively, to somewhat merge it with the next one (2.)

2. A tutorial on statistical-learning for scientific data processing: This looks like excellent material (from @GaelVaroquaux I think?), and I believe this should actually be our whole “Tutorials” page. There are however a few issues with this guide:

   • it’s quite old (up to 9 years old), so some sections might not follow our current best practice
   • ~there are layout issues~ as e.g. here (fixed in #18261)
   • it’s hard to navigate between sections, since the sidebar isn’t updated as one might expect.

   I would suggest to:

   • make a careful pass over it and update it to our recommended best practices / introduce recent tools
   • ~fix the layout issues~ (done in #18261)
   • fix the sidebar issues
   • make this the entire “Tutorials” section of the docs
   • maybe integrate stuff from 1.

3. Working With Text Data: This thing looks like it could be just an Example, so we can probably remove it from the Tutorials page. I haven’t checked but I think we already have similar examples, so we could merge this one with some others

4. Choosing the right estimator: I think our users love this pic, and @amueller (the author) now hates it ^^. Maybe it could just stay there, or we could transform it into an example.

5. External Resources, Videos and Talks: this section presents some super old tutorial videos, the most recent is from 2013. I think we could:

   • update it to the more recent tutorials e.g. those given recently at Scipy and EuroScipy.
   • Make it a subsection of 2., if 2. becomes the whole “Tutorials” page as suggested.

Of course these are only suggestions, I’m happy to discuss alternatives.

[cmarmo]

* fix layout and sidebar issue from 2. -- easyish

Some time ago I opened #17865 … Since the beginning I feel like I’m not really lucky with website things… should this be a good starting point?

[TomDLT]

How would you feel about adding tags, e.g. “Beginner”, “Advanced”, “New in 0.XX” etc.? I’m picturing these as labels e.g. on the rendered image in the gallery, but we could also use them for filtering?

I really like the tag/filter idea from #16601. It will be more complex to implement than the multiple galleries solution, but it is more flexible, it does not break URLs, and it keeps all examples at the same place which improves discoverability.

For the tutorials, I think the priority is to rework them, as proposed in this RFC plan, and part of this reworking could be to format them as a gallery of long notebook-style examples.