Installation instructions are abominably awful, feel like abandonware

Đang mở
  • Có gì không ổn?
#156 6 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
35/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
html, hugo
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu với landing page và phần cài đặt được liên kết, sau đó tìm source Hugo tương ứng trong repository của website. Xem xét các tab cài đặt, cảnh báo và liên kết pipx từ góc nhìn của người mới; được coi là hoàn tất khi landing page dẫn đến phần cài đặt và trình bày rõ ràng một phương pháp được khuyến nghị mà không có hướng dẫn gây nhầm lẫn.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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?

Ngôn ngữ chính
HTML
Star
39
Fork
21
Merge trung bình
15 phút
Pull request đã merge (30 ngày)
3

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của python-poetry/website

Tất cả issue của python-poetry/website

Issue tương tự

Thêm issue về Documentation

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.