conda-forge / conda-forge/conda-forge.github.io

Introduction should be crisp, needs re-ordering

Ouverte
#1,282 12 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Discussion Docs Outreachy
Langage dominant
JavaScript
Étoiles
170
Forks
320
Merge moyen
2 j 10 h
PR mergées (30 j)
5

Description

The introduction page in the docs:

https://conda-forge.org/docs/user/introduction.html#what-is-conda-forge

The opening section is titled, 'What is conda-forge?'.

It is followed by:
1. an incomplete definition of conda-forge (#1277).
2. Then this line:
>Missing a package that you would love to install with conda? - Chances are we have already packaged it for you!

For me, as a new user, this line was not immediately very clear.

Am I missing a package that I would love to install with 'conda'? What does it mean? Does it mean 'is there a package I want to install using `conda install` only, but I'm unable to find it on the default conda channel' ? [I could reach this understanding only after some discussion with @viniciusdc .]

Chances are conda-forge has already packaged it for me.
But so might have many other channels. Why should I use conda-forge?
[The answer to that question comes in the next section. 'Why conda-forge?' The flow is hence broken. ]

3. Then this:
>You can search for packages online. Look out for packages provided by our conda-forge organization.

Again, what this is trying to convey is not immediately clear. Infact, these two sentence even seem disconnected.
[ A better alternative could be, 'Search for packages on anaconda.org and look for the ones with conda-forge as owner'. ]

4. Then this:
>Cannot find a package or only outdated versions of a package? - Everybody is welcome to contribute to our package stack! Please refer to Becoming involved, for an overview over how to start contributing.

But why?
Why is this information given under 'What's conda-forge?'

All these pieces of information somehow seem disconnected. There is a lack of flow within the introduction.

Suggested solution:

I think, we need to re-order and re-organize 'what goes under which heading'.

'What is conda-forge?' should only contain a proper definition of conda-forge.
This should then be followed by the 'Why conda-forge?' section, because after understanding that conda-forge is a channel that provides packages, the question that comes to mind is 'why should I use conda-forge over anything else?'

After that we tell the user how to check if a package they are looking for is available on conda-forge channel or not.
>You can search for packages online. Look out for packages provided by our conda-forge organization.

We then say,
>Cannot find a package or only outdated versions of a package? - Everybody is welcome to contribute to our package stack! Please refer to Becoming involved, for an overview over how to start contributing.

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.