Thanks to visit codestin.com
Credit goes to github.com

Skip to content

RFC Plan for reworking the tutorials #18257

Open
@NicolasHug

Description

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    DocumentationModerateAnything that requires some knowledge of conventions and best practiceshelp wanted

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions