search

python-poetry / website

Source for the official Poetry website
https://python-poetry.org
35 stars 19 forks source link

Installation instructions are abominably awful, feel like abandonware #156

Open alexchandel opened 1 week ago

alexchandel commented 1 week ago

Installation should be easy, but Poetry is anything but, due to this website.

First, the landing page does not even mention or directly link to installation. If I arrive there and think "this looks cool, where do I click to install", there is nothing. No "click here to install", nothing. I have to guess that Documentation > Introduction contains an Installation section.

That installation section begins with a confusing warning about virtual environments, but FAILS TO RECOMMEND an installation method. Instead it has 4 tabs.

The first is pipx. Foolish. If you want adoption, your first installation method should not require another 3rd party program. A third of potential new adopters have just clicked away, assuming Poetry is too much trouble and too niche to even install itself.

Then there is With Official Installer. That sounds promising. Why is "the official installer" not the first tab? New users are confused. But it begins with this warning:

image

WTF does this even mean? Is install-poetry.py the same as "The installer script" we are installing? Why is a red "STOP" error message at the top of this "official" installation method? Should a new user conclude that this "official" "installer script" is now deprecated in favor of something else? 60% of your remaining potential new adopters have clicked away, confused and annoyed at the troublesome abandonware they were recommended. Note that the linked installer script seems to have some issue with current Windows 11 + Python 3.13.

Obviously, someone who has used Poetry for years knows the answers to the above questions, but that's not the point. These are all problems new users encounter when directed to use Poetry. Read your website from the point of view of a new user you're selling to. Make a recommended TLDR "DO THIS IF UNSURE" method plainly visible as the first tab, one that applies to new users who don't use pipx or popy or whatever trend of the year, without any years-old warnings that don't apply to them. New users want simplicity, not complexity. They are coming to Poetry to make their lives easier.

When I point dev after dev to poetry and their installation experience is the above, that's a problem. Companies spend millions on SEO / easy onboarding. Poetry could at least spend 5 minutes to stop driving away 90% of its potential new adopters.

PS

Let's follow the first tab, pipx, as a new user. Step 1 is "Install pipx":

If pipx is not already installed, you can follow any of the options in the official pipx installation instructions. Any non-ancient version of pipx will do.

Ok, I guess we can install one third-party tool, let's follow that link and ...

image

lol. Is the problem evident yet?

dimbleby commented 1 week ago

please submit a pull request showing the five minutes worth of effort that you would like to see done

alexchandel commented 1 week ago

As I am not a maintainer, I cannot declare what the "recommended method" is.

dimbleby commented 1 week ago

constructive suggestions are surely welcome. As it stands, I think it is unlikely that this issue report will produce useful change.

alexchandel commented 1 week ago

This is a constructive issue from a longtime user who doesn't want Poetry to wither, relaying hard experiences from users I've recommended Poetry to. I cannot tell you what the "recommended method" should be. I'm just a longtime user. My constructive suggestion is:

  1. Choose preferred installation method (I cannot do that, and that is the biggest step)
  2. Put the install oneliner on your landing homepage like macOS Homebrew does, or
  3. Make it the first tab in your install docs, explicitly mark it as "Recommended", and make Step 1 a single self-contained instruction with no "STOP" error bubbles or alternatives that are confused as Step 2s. And make sure that installation method works on both Unix and the latest Windows.
dimbleby commented 1 week ago

pipx has been the preferred - and first-mentioned - installation method since https://github.com/python-poetry/poetry/pull/8090

pull requests to improve clarity are invited.

jey-exp commented 1 week ago

@dimbleby I can feel the efforts contributors have put into poetry to make it awesome. I love it! But the installation guide is bit ambiguous and can be improved. Anyways lets fix it, making it better for other users.

I am willing to help with it, will discuss more on this in discord.