Installation instructions are abominably awful, feel like abandonware

未關閉
  • 哪裡不對？
#156 6 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

評估

難度
3/5
預估耗時
1-2 天
新手友好度
35/100
Issue 類型
文件
描述清晰度
基本清楚
活躍度
停滯
技術堆疊
html, hugo
領域
documentation

研究方向

從連結的登陸頁面和安裝區段開始，然後在網站儲存庫中找到相應的 Hugo 原始碼。從新手的角度檢視安裝分頁、警告和 pipx 連結；當登陸頁面能引導使用者進行安裝，並且清楚呈現一種建議方法而不會造成指引上的混淆時，即可視為完成。

由索引模型根據 Issue 內容生成。

描述

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?

主要語言
HTML
星號
39
分支
21
平均合併
15 分鐘
30 天內合併 PR
3

環境準備

這個專案沒有提供開發容器、Dockerfile 或貢獻指南，環境需要你自己搭建：先看它的 README，通用步驟見我們的新手貢獻指南。

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

python-poetry/website 的其他 Issue

查看 python-poetry/website 的全部 Issue

相似的 Issue

更多 Documentation Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。