Introduction should be crisp, needs re-ordering

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

1. 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’. ]

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

[ForgottenProgramme]

@ocefpaf, hey! 😃

Right. Smaller PRs for each ‘part’ of this issue should be a good idea. And no. The contribution period for Outreachy hasn’t started yet. It starts from 29th this month.

[ocefpaf]

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

This is the right approach to this problem. Thanks @ForgottenProgramme.

The question you are raising are surprisingly not that easy to answer though! We have our heads buried in conda-forge for a few years and it is hard for us to see those problems clearly and writing something better. With that said… Let’s track those questions here and, if you can, link them to “bite-size” PRs. You don’t need to a address them all now. (I believe outreachy did not start yet, right?)