RFC Plan for reworking the tutorials

[NicolasHug]

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 [MRG] DOC New Getting Started guide #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 DOC Tutorial structure and layout #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 DOC Tutorial structure and layout #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.

[NicolasHug]

In terms of timeline and PRs, I imagine this could be done as:

• update 5. -- easy
• move 3. to an example -- easyish
• move 4. to an example -- easy
• fix layout and sidebar issue from 2. -- easyish (Layout issues fixed in DOC Tutorial structure and layout #18261)
• update 2. and maybe integrate 1. (or remove it) -- hard, big PR

[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]

I strongly agree with all the propositions. We should also add a link to the excellent "Quick Start" guide at the top of the tutorial page.

[GaelVaroquaux]

An additional suggestion on this, using examples:

• We could do 2 galleries (sphinx-gallery now supports multiple galleries):
  • "Tutorial examples", where we move the most didactic examples and expand them. Using "notebook style examples" enables to be very didactic
  • "Snippet examples" (don't know if it's a good name), where everything else goes.
• We would put more focus on the "Tutorial examples" by:
  • Putting them more visible on the website
  • Having two backlink minigalleries at the bottom of API documentation, with the first one being examples from the tutorial examples, and the second one being snippets
• Because this reorganization will break links (eg from Google), hence we should keep the same links for the "snippets", which will be most of the examples, and do redirect pages (possibly manually) for the tutorial examples that we move.

[NicolasHug]

I had a more general proposal about examples (#16601) though I'm not sure about the feasibility. Having 2 galleries could be a good alternative.

(But this is only marginally related to this issue IMHO, which is more about the https://scikit-learn.org/stable/tutorial/index.html page)

[GaelVaroquaux]

Thanks!! You are right. I found the wrong issue (I was looking for the issue on the examples). I'll update the other issue.

[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.