IMO, I like See :term:`random_state`.. I think that it allows to highlight where the random_state or n_jobs is used inside the algorithm itself (as you mentioned).

On the side, I can recall some discussion with @lesteve IRL which point me out that developers are using the docstring directly from terminal, and for which hyper-links could make it difficult to find the detailed documentation.

However and as a bottom-line, I would go for the less verbose version since I personally think that newcomers are more prone to use online (HTML) documentation and that n_jobs and random_state are hugely redundant arguments and for which the use is probably trivial.

On the side, I can recall some discussion with @lesteve IRL which point me out that developers are using the docstring directly from terminal, and for which hyper-links could make it difficult to find the detailed documentation.

Fine with me, I guess people will need to learn that :term: means going to the glossary and where the glossary lives.

We could use "see the glossary"

The issue that I see with this is that many users look at the docs via jupyter notebooks and I don't think the links will work there, right?

Dear core-devs, after discussion with @glemaitre, this issue is indeed a good candidate for sprints. It has been splitted in more specific issues. I'm wondering if we can close this one, being an RFC on which apparently consensus has been obtained, in favour of #10548 and #14228 , for which I'm trying to summarize the list of modules that still need an update. Also, I'm checking the memory parameter that could probably benefit of the same clarification. @jnothman, WDYT? Thanks!

in favour of #10548 and #14228

... #14228 is indeed a bit different ... maybe I can open one specifically for referring to Glossary for n_jobs? Sorry for the noise... trying to clarify for beginners... like me...

I don't think #14228 is so different, and yes I'm happy to close this as the work is covered by those other issues mostly. But to be sure, solving these issues for an estimator requires understanding how that estimator works, and how to investigate where the randomisation/parallelisation is used. It's quite a challenging issue for a newcomer (but not inherently requiring a lot of prior scikit-learn knowledge).

Yes, happy to see memory refer to Glossary, but it's much less frequent and much less ambiguous as to what it's used for.

The conclusion of these discussions was that we are avoiding duplication of docstrings by referring to the glossary.
The caveat as pointed out by @amueller and @glemaitre was that it is not possible to see this via terminal or jupyter notebook.

One approach that we took in kartothek was by introducing decorators on top of each function that auto-fill the remaining parts of docs. For e.g

• function delete_dataset has docstring that are filled by the decorator which results in this

If maintainers like this idea, I could propose a draft.