Add hyperlinks for clarity whenever possible

[ArturoAmorQ]

Add hyperlinks whenever a new concept is introduced (and not covered in detail), or as a reminder in key places. This may help clarifying the content without adding more text.

• Most of the times the concepts are covered in the scikit-learn user guide. Example:

  • Add link to the documentation for terms mean squared error, mean absolute error and R^2 in this notebook
  • For the term API introduced at the beginning of M1.

• Some concepts are not in the user guide but we could find a way to link them to the Glossary. Examples:

  • Add link to the Glossary for the word "uncertainty" in this notebook (See #426)
  • Add link to the Glossary the first time we introduce the word "hyperparameter" in this notebook and in quiz M3.01 (to address this post in the forum)

• Other concepts may be pointed to external material "to go beyond", e.g. "interpretability" or "voting".

[lesteve]

I think the main problem here is that we don't have a technical way to do links between different places of the MOOC in a way that works for all setups: JupyterBook, Jupyter notebook outside FUN (used for in-person courses), and Jupyter notebook inside FUN

• we can do links between documents in JupyterBook but then they would use MyST-specific syntax so they would not work in Jupyter notebook outside FUN. Maybe this is doable to use our notebook conversion script to rewrite the links although this may not be trivial at all
• even if we manage to do the previous point, we would need to rewrite automatically the notebooks inside FUN to point to the FUN URL (e.g. glossary). That would mean we need:
  • custom logic inside JupyterHub to convert the notebooks
  • a URL correspondance table between JupyterBook and FUN so that the notebooks point to a URL within FUN

I think our general approach so far (not ideal I know) was:

• let's try to explain well something the first time we encounter it (potentially also the next few times)
• let's use the glossary as a fall-back when you don't remember the meaning of a central concept

[lesteve]

Also I feel somehow that https://github.com/INRIA/scikit-learn-mooc/issues/420 could be another way to help find parts of the MOOC related to a given concept

[ArturoAmorQ]

If I understand correctly, #420 proposes directing the search results links towards .github.io. That might be the easiest solution in both cases.

This search tab could also be a place to remind people that they can browse the material on our .github.io, since this is slightly more convenient that clicking around in FUN.

Caveat: the state of the .github.io is not completely is not in sync with the user Jupyter notebooks, but I think that's fine ...

[lesteve]

If I understand correctly, #420 proposes directing the search results links towards .github.io. That might be the easiest solution in both cases.

It would be inside an iframe in FUN, so that would still give you the feeling you are inside FUN, the same way the forum tab on the top right gives you the feeling you are still inside FUN although the forum is in an external web page.

[ArturoAmorQ]

Worst case scenario, concepts that are not covered in the user guide could be linked to wikipedia, what do you think?

[lesteve]

Using an external resource is fine I think.

The problem is that it is not so easy to find good resources at the level we want. The user guide is very often not such a good place for beginners, for example look at this section for nearest neighbors classification: https://scikit-learn.org/stable/modules/neighbors.html#nearest-neighbors-classification.

Finding a compromise solution where we hard-code links to .github.io (rather than making sphinx-like links between documents) could be a hacky yet good enough compromise. Other opinions more than welcome!

Note to our potential future selves: we can use linkcheck like this from time to time to make sure links still work:

jupyter-book build --builder linkcheck jupyter-book

[lesteve]

This would help to have specific points to be addressed (there are a few at the beginning already). Generic issues like this tend to rot with time.

[kinow]

Hi all :wave:

scikit-learn beginner here, with a little background on ML/NLP. I'm doing the MOOC, and as mentioned in #623, search for things like "!wiki Bayes error rate" on DDG, or opening scikit-learn.org and searching in the site for some terms. But most of the time I use Wikipedia.

It'd be great to have links like foot notes (if we don't want to have links distracting users), as an extra section in the lesson like “References” or “Glossary”, etc., or maybe HTML links.

Thanks! Bruno

p.s.: I just tried searching "!scikit make_pipeline" and it didn't work, so I asked DDG to add a new bang for it :man_shrugging: not sure if it'll be accepted, but doesn't hurt to try. At least that way I'll be able to search these terms quicker until we have hyperlinks or some other fix.

[GaelVaroquaux]

maybe HTML links.

I think that turning some word into HTML links to relevant wikipedia pages would be useful, and it would not add "noise" to the current material (we struggle to keep it not too long).

I can only speak for me, but I think that a PR doing that would be welcomed.