Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README.md quite confusing: reorganisation needed #685

Open
paugier opened this issue Nov 27, 2024 · 0 comments · May be fixed by #686
Open

README.md quite confusing: reorganisation needed #685

paugier opened this issue Nov 27, 2024 · 0 comments · May be fixed by #686
Labels
documentation Improvements or additions to documentation

Comments

@paugier
Copy link

paugier commented Nov 27, 2024

I participate (as a teacher) to a Python training. There were many Windows and macOS users and the README page leads to confusions.

We gave this link https://github.com/conda-forge/miniforge. I now realize that we should have given https://conda-forge.org/download/ which may be better (but actually not really because it lacks very important information to get a correct setup).

Most users reading the text in https://github.com/conda-forge/miniforge want to install the latest version of miniforge.
Currently the explanation how to do that is spread in different parts of the README. There are sections Download, Installation and Usage.

A Windows user first reads the section Download and then do not read the rest of the README. He/she clicks on https://github.com/conda-forge/miniforge/releases or on latest in the table and obtain a page which is not very useful with plenty of links with complicated names. The deprecated names starting with Mambaforge or Miniforge-pypy3 appear first. In practice most participants to the training were completely lost.

For Windows the interesting link is now https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe

It seems to me that the README should be reorganized with a first section Install with subsections:

  • Windows
  • Unix-like platforms (macOS & Linux)
  • macOS
  • Specificity for CI pipeline

Commands and actions needed to complete the installation should also be mentioned. There should be in this section enough information to get a decent installation with at least condabin in the path (not only with Miniforge Prompt, which is of course very bad in 2024 since Windows users can and should use a better shell and a better terminal).

So we need some worlds on conda init and conda config --set auto_activate_base false.

I will try to submit a PR to improve the situation.

@paugier paugier linked a pull request Nov 27, 2024 that will close this issue
@hmaarrfk hmaarrfk added the documentation Improvements or additions to documentation label Dec 11, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Development

Successfully merging a pull request may close this issue.

2 participants