-
Notifications
You must be signed in to change notification settings - Fork 883
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
Suggestion: Have a "Quick Start" guide #688
Comments
So pypi.org does mention pip on every project page indirectly via the installation instructions, so I would assume that's where it should be linked from. If the true target is a beginner just going straight for it then they aren't going to poke around but go straight to the project they want. So I would think a link around that As for where a dirt-simple HOWTO should live, I would think as an opener to https://packaging.python.org/tutorials/installing-packages/ would work in a call-out box like a note. It can say, "Summary: create a virtual environment, activate it, and then do `python -m pip install X; here's a link to the conda equivalent of these instructions". |
#396 covers the fact that what we'd really like to do is have a separate "How to make sure your environment is properly configured" guide, rather than having a smattering of that content embedded directly in the package installation tutorial. Then the installation tutorial could be made a lot simpler, with only folks that have problems needing to go to the more in-depth environment setup guide. |
I think it would be great if in addition to the in depth tutorial, there is actually a quick start guide.
To elaborate, if a brand new user of Python lands on https://pypi.org/, they see a link that says "learn about installing packages" that takes them to the tutorial. The tutorial is very lengthly, explains about the requirements, about venvs, about installing from requirements file and so on.
All of these are fine and useful for someone who comes to the page to really learn about how the installer works.
Consider scenario of a newcomer to Python, who isn't really in it to learn how pip works. Perhaps they were told by coworker or someone, "just use django/numpy/pillow/etc. All you need is Python and then pip install it". In this situation, their main goal is start using the third party libraries. So what happens then? They did exactly that: download Python from python.org, (3.8 because its new), and immediately typed
pip install ...
(that's what they were told). Did not have time to learn about pip/venv/ whatsover. But as you can predict, it doesn't work. For example, in MacOS,pip install ...
likely installs it to their Python 2.When people come to me with this problem, the easy answer I gave them usually is simply "you need to do python3.8 -m pip install .. and preferably in virtual environment". That's usually enough answer for them, they're not looking to learn about pip/virtualenv/packaging. They just want to start using the third party library.
The above scenario happens quite often, and I've been thinking a lot on how to improve the experience for people in these scenarios.
Some questions I asked myself:
should Python installer be improved? Should it teach people about pip/venv, etc? At the moment, the Mac installer provides a link to PyPI, which links to the tutorial.
should Python.org download page be improved? Should it be more explicit and say "you may need pip/virtual environment in order to install additional packages." At the moment, all we have is a link at the very bottom (way past all other info like, license, gpg key, release schedule etc), and all it says "looking for 3rd party modules? go to PyPI!". It is not clear to a new comer that this is where they need to go if they are going to install anything with
pip
.when we land on pypi.org,
pip
is not mentioned anywhere. How would a newcomer, who was told topip install X
knows that they should be going to the tutorial page?Since pypi.org is the place we point people to (from Python installer and from python.org downloads page), I wonder then, perhaps, a small step to improve this experience is if there is a quick "Howto". For example, a quick blurb that says: "to install a package do: python -m pip install X. Go to tutorial to learn more!"
So that's the background on why I'm suggesting this improvement. Thanks for considering, and let me know if I can help clarify anything, and sorry for rambling a bit.
The text was updated successfully, but these errors were encountered: