Skip to content

RFC Plan for reworking the tutorials #18257

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
NicolasHug opened this issue Aug 25, 2020 · 7 comments
Open

RFC Plan for reworking the tutorials #18257

NicolasHug opened this issue Aug 25, 2020 · 7 comments
Labels
Documentation help wanted Moderate Anything that requires some knowledge of conventions and best practices

Comments

@NicolasHug
Copy link
Member

NicolasHug commented Aug 25, 2020 •
edited
Loading

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
Copy link
Member Author

NicolasHug commented Aug 25, 2020 •
edited
Loading

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

@NicolasHug NicolasHug changed the title Plan for reworking the tutorials RFC Plan for reworking the tutorials Aug 25, 2020
@cmarmo
Copy link
Contributor

cmarmo commented Aug 25, 2020 •
edited
Loading 

* 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
Copy link
Member

TomDLT commented Aug 25, 2020

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.

This was referenced Aug 26, 2020
Merged
Merged
@NicolasHug NicolasHug added Easy Well-defined and straightforward way to resolve help wanted Moderate Anything that requires some knowledge of conventions and best practices labels Sep 15, 2020
@GaelVaroquaux
Copy link
Member

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.

@GaelVaroquaux GaelVaroquaux removed the Easy Well-defined and straightforward way to resolve label Nov 5, 2020
@NicolasHug
Copy link
Member Author

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
Copy link
Member

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
Copy link
Member

TomDLT commented Nov 5, 2020

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.

@NicolasHug NicolasHug mentioned this issue Nov 15, 2020
Closed
@cmarmo cmarmo mentioned this issue Dec 5, 2020
Closed
@ogrisel ogrisel mentioned this issue Jun 25, 2021
Merged
@cmarmo cmarmo mentioned this issue Feb 22, 2022
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation help wanted Moderate Anything that requires some knowledge of conventions and best practices
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@GaelVaroquaux @NicolasHug @cmarmo @TomDLT