Introduction should be crisp, needs re-ordering

[ForgottenProgramme]

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 (A proper 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.

[viniciusdc]

@beckermr @CJ-Wright @ocefpaf I agree we could enhance our introduction, any comments ?

[beckermr]

Go for it. Let's make prs and people will review them. :)

[viniciusdc]

Actually I think that it would be a good idea to rebuild that intro from scratch. Maybe a good project to think of... we could also establish a link with #1208 (maybe #998 too?)

[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?)

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

[Uttam-Singhh]

Hey, Can I work on it as an Outrechy contribution?
Please assign me!

[prachinandi]

I was speculating the introduction page of Conda-forge, and what I contemplated was:
The brief introduction page should have a precise and clear about info, which I think we can take frm (https://conda-forge.org/#about) as someone like me who is new to this org could get to know all about conda-forge, by reading this about info like, what is the main function of this organization.

As @ForgottenProgramme told that these lines "Missing a package that you would love to install with conda? " are not needed in the "what is conda-forge" we can add these lines in "why conda-forge?"

What if we don't use the question mark for every subtitle, in the introduction page, because that seems like a FAQ section .

[benny-coy]

Hello,
I am Patience Akpan, an Outreachy applicant 2021. and here is my contribution on Introduction should be Crisp, needs re- ordering #1282

First, when i opened the introduction page in the docs: (As my first time here)
https://conda-forge.org/docs/user/introduction.html#what-is-conda-forge

I read the opening section titled, 'What is conda-forge?'.
What is Conda-forge seem like About Conda-forge: (example; is a community effort that provides conda packages.

So, i support that What is Conda- forge is suppose to be a complete definition of Conda-Forge (example; Conda-forge is a package for a wide range of software such as.........etc.

Secondly, Missing a package that you would love to install with conda? - Chances are we have already packaged it for you! P
I was totally disconnected here, For me, as a new user, this line was not immediately very clear. because the next thing i would have love to know is what Conda-Forge can do and why i should use it, if possible compare to others softwares.
I also suggest that these information can come under How can i Install Packages from conda-forge.

So, i support that "All these pieces of information somehow seem disconnected. There is a lack of flow within the introduction."
Also,these pieces of information is not suppose to be there.

Thirdly, You can search for packages online. Look out for packages provided by our conda-forge organization.
when i read this line "You can search for packages online", i am like what packages?.

So, i support that what this is trying to convey is not immediately clear. Infact, these two sentence even seem disconnected.
I think that Missing a package that you would love to install with conda? - Chances are we have already packaged it for you! is pointing to ** You can search for packages online. Look out for packages provided by our conda-forge organization**.
I think this can be reframe as Missing a package that you would love to install with conda? You can search for our packages online.
I also suggest that these information can come under How can i Install Packages from conda-forge?.

Thank you for this opportunity to contribute.

[benny-coy]

@viniciusdc , Can I work on this? i am an Outreachy applicant. Please assign me!

[PrernaSingh587]

@viniciusdc , Can I work on this? i am an Outreachy applicant. Please assign me!

Hi, this issue is currently open for discussion. So it has not been assigned to anyone. But you can post your thoughts and carry forward the discussion which could be beneficial in reforming the intro. :)

[victory-lydia]

Hi!
@viniciusdc can I work on this issue

[AnishaSingh0118]

@ForgottenProgramme @viniciusdc I am an Outreachy applicant, looking forward to start my first contribution with this good first issue, as this issue is currently open and has not been assigned to anyone.I would love to work on this issue so please kindly assign me this issue.