改進 pip 的文件¶
問題¶
我們希望證明 官方 pip 文件 是否能幫助使用者解決 pip 問題。我們還想識別文件中內容和結構的潛在改進方式。
研究¶
訪談¶
我們訪問了特別討論文件的 pip 使用者。在這些訪談中，我們詢問了以下問題
他們在使用 pip 時遇到的問題，以及他們如何解決這些問題 (重點在於他們使用了哪些資訊來源)
他們如何評分 pip 的文件，以及我們可以採取哪些措施來讓文件更有用
他們認為哪些文件 (來自其他專案或語言) 很寶貴，以及原因
問卷調查¶
我們透過兩次問卷調查收集了文件回饋
在我們對 pip 使用者進行的問卷調查中，我們詢問了「你希望如何獲得 pip 協助？」
我們還針對 pip 文件發布了一份專門的問卷調查
關鍵字研究¶
我們使用關鍵字研究工具來了解人們在用搜尋引擎解決 pip 問題時使用的字詞（「關鍵字」）。
其他研究方法¶
我們還
要求志工參與日記研究，記錄他們解決 pip 問題的經驗。不幸的是，由於社群缺乏興趣，因此沒有完成這項研究。
要求使用者針對 pip 文件網站提供回饋：
很不幸地，我們沒有透過這項工作收集到任何有用的意見回饋在 pip 文件中安裝分析。我們正在等待這項功能合併，並開始提供有用的資料。
結果¶
總計，我們
進行了 5 次 pip 文件使用者訪談
收到 141 份對「你希望如何獲得 pip 協助？」問題的回應
收到了 159 份文件調查問卷的回應
我們發現，大多數使用者並未充分使用社群中的 pip 文件，許多使用者甚至不知道有這份文件。相反地，大多數使用者求助於 Google、Stack Overflow 等常見工具來解決他們的 pip 問題。
回應「當你在使用 pip 時遇到問題，你會怎麼做？」問題時（多選）
81.9% 的受訪者會用 Google 搜尋
56.9% 的受訪者會在 Stack Overflow 上搜尋或提問
33.8% 的受訪者會從命令列使用 pip 說明
25.6% 的受訪者會前往 pip 文件
20.6% 回覆者會前往 Python 封裝使用者指南
8.1% 回覆者會在論壇、社群看板或聊天頻道提問
根據問卷調查結果，使用者認為 pip 的文件
稍微比無用更有用
稍微比不清楚更清楚
意見不足
從兩項調查和使用者訪談中獲得的常見回饋包括
文件在搜尋引擎結果中表現不佳
樣式和版面過時（注意：此回饋是在新主題部署之前收集的
關於如何解決常見問題或達成特定目標的指引和範例不足
文件資訊架構難以導覽（使用者指南的龐大結構是個問題），也沒有將最實用的內容優先排序
應該有針對不同使用者情況提供更多說明（例如他們使用的作業系統）
文件範圍不明確
文件應該要承認 pip 存在於其他封裝工具的生態系統中
“必須有一種（最好且僅有）明顯的方法。” - 換言之，文件應該提供更強而有力的建議
雖然有些使用者提到影片很有用，但更多人表示影片太長或不適用於他們使用 Pip 時遇到的問題。
有些使用者提到，面對面的支援、論壇或聊天很有用，而且許多人不知道現有支援/社群管道。
另外，數位使用者也指出，改進 Pip 的錯誤訊息有助於降低對更完善文件的需求。
從我們的關鍵字研究中，我們找出七種查詢類型：「關於 Pip」、「安裝 Pip」、「卸載 Pip」、「更新 Pip」、「使用 Pip」、「錯誤」和「其他」。
請參閱關鍵字研究結果
關於 Pip¶
什麼是 Pip
什麼是 Python 中的 Pip
什麼是 Pip Python
Pip 是什麼意思
Pip 代表什麼
Pip 代表什麼 Python
Pip 意指
安裝 Pip¶
取得 Pip
Python 安裝 Pip
安裝 Pip
安裝 Pip
如何在 Python 中安裝 Pip
如何安裝 Pip
如何下載 Pip
如何取得 Pip
如何檢查 Pip 是否已安裝
在 Mac 上安裝 Pip
如何在 Mac 上安裝 Pip
在 Mac 上安裝 Pip
在 Linux 上安裝 Pip
如何在 Linux 上安裝 Pip
如何在 Linux 上安裝 Pip
如何在 Ubuntu 中安裝 Pip
如何在 Ubuntu 中安裝 Pip
在 Ubuntu 中安裝 Pip
在 Ubuntu 中安裝 Pip
Pip Windows
在 Windows 上安裝 Pip
在 Windows 上安裝 Pip
如何在 Windows 上安裝 Pip
如何在 Windows 中安裝 pip
如何在 Windows 中安裝 pip
如何在 Windows 中使用 pip 安裝
如何在 Windows 10 中安裝 pip
如何在 Windows 中執行 pip
解除安裝 pip¶
如何解除安裝 pip
解除安裝 pip
pip uninstall
更新 pip¶
如何更新 pip
如何升級 pip
pip 更新
pip 升級
升級 pip
如何在 Windows 中升級 pip
使用 pip¶
如何使用 pip
如何使用 pip 安裝
如何使用 pip 安裝
如何使用 pip python
如何透過 pip 安裝
如何執行 pip
python 如何使用 pip
pip 安裝 requirements.txt
pip requirements.txt
pip freeze
pip 更新套件
pip 安裝特定版本
pip 升級套件
pip 解除安裝套件
錯誤¶
沒有名為 pip 的模組
找不到 pip 指令
未辨識 pip
「pip」未辨識為內部或外部指令、可執行程式或批次檔。
-bash：pip：找不到指令
pip 未辨識為內部或外部指令
pip 安裝無效語法
其他¶
如何將 pip 加到路徑中
如何檢查 pip 版本
pip 如何運作
pip 安裝套件安裝到哪裡
pip 與 pip3
pip 安裝在哪裡
「安裝 pip」查詢的盛行強烈建議改善目前的安裝文件，且使用者正在尋找特定於作業系統的解決方案。
「關於 pip」查詢也建議初學者會受惠於更能解釋 pip 基礎的說明文件，例如 pip 是什麼和它在做什麼。
建議¶
根據我們的研究，我們建議 pip 團隊
修改文件結構
將整體頁面分成具有不同主題的獨立頁面，並加上適當的 meta 標記。這將有助於文件在搜尋結果中的排名更高，因為 81.9% 的使用者使用 Google 來解決其 pip 問題。
優先處理最常用的功能（查看「購買功能」結果以取得指引）
在文件中增加「疑難排解」部分，說明常見問題、解釋錯誤訊息，並告訴使用者可以在哪裡找到更多說明
透過下列方式提供有關 pip 在 Python 封裝生態系統中角色的更多內容：
引介使用 pip 必備的打包觀念
說明 pip 在打包生態系中的角色/範圍
比較 pip 和其他工具
寫一本適合新手的指南，帶領新進 pip 使用者認識使用 pip 最基本的功能所需的一切。這應包括說明 pip 範圍以外的觀念（例如如何開啟和使用終端機、如何設定虛擬環境），這些觀念可能會阻礙使用者順利使用
在每個網頁（適當的情況下）加入下列各節：
「秘訣和竅門」- 必知事項 / 陷阱
「疑難排解」- 可能出現的錯誤訊息和建議的解決方案。適當的情況下，應連結到疑難排解單元中的內容。
「另見」（連結到外部資源 - 例如有用的 stack overflow 問題、部落格文章等等）
原則上，編寫的內容應
帶有觀點。優先採用絕大多數情況下有效的解決方案，同時在「秘訣和竅門」、「疑難排解」、「另見」等內容中指明可能的特殊情況和解決方法
使用關鍵字增加搜尋結果能見度
提供不同情境下的說明 - 例如 Windows、Linux、MacOSX 使用者的說明
增加與外部來源的交互連結，包括 packaging.python.org
建議的網站地圖¶
根據以上的使用者輸入，我們擬出一份建議的網站地圖（連結開啟較大格式的圖片），以協助按照以上的建議重新發展 pip 文件。
參閱此網站地圖的備註事項
節點 1.0：快速參考¶
頁面宗旨
讓 pip 使用者能快速概觀 pip 的安裝方式，以及如何使用 pip 的主要功能
連結到文件中的其他（更詳細的）區域
建議的內容
快速安裝指南，包括如何使用虛擬環境。這對想要在其機器上安裝超過一個 Python 專案的使用者來說是必要的。
常見指令 / 任務（根據購買功能的資料）
節點 2.0：關於 pip¶
頁面宗旨
向新使用者介紹 pip
建議的內容
介紹 pip 作為一個命令列程式
說明何謂命令列，以及如何在不同的作業系統中使用
說明什麼是 pip/pip 執行什麼功能，以及 pip 的全名
連結到打包觀念（節點 2.1）
說明 pip 的範圍（例如安裝和移除套件），並連結到其他工具（節點 2.2）
節點 2.1：打包觀念¶
頁面宗旨
為新進的 pip 使用者介紹打包觀念
建議的內容
何謂套件？
有哪些元件類別？例如，檔案類型
什麼是元件版本控管／需求指定公式是什麼？（註記：在此說明潛在相依性的衝突）
從何處取得元件？
我應該如何控制系統上的元件安裝方式（例如，虛擬環境和環境隔離）
如何還原環境／確保可重複性？（例如，需求檔案）
我需要知道哪些安全性問題？（例如，hash 檢查、PyPI 名稱搶註）
連結至節點 2.2（「pip 與其他封裝工具」）
節點 2.2：pip 與其他封裝工具¶
頁面宗旨
將 pip 與具有相同範圍的其他工具進行比較
強調 pip 存在於封裝生態系統內，並連結至其他封裝工具
建議的內容
將 pip 與其他安裝工具進行比較，例如 poetry、pipenv、conda。每個工具的功能、優點與缺點有哪些？為什麼封裝使用者選擇一個工具而不是其他工具？
簡要介紹其他封裝專案。連結至 https://packaging.python.org/key_projects/
節點 3.0：安裝 pip¶
頁面宗旨
協助 pip 使用者安裝 pip
建議的內容
重構目前頁面，強調不同作業系統的路徑
加入「秘訣技巧」、「疑難排解」和「參閱」等區段（連結至外部資源）以提供其他說明
節點 4.0：教學課程¶
頁面宗旨
提供 pip 教學課程的入門途徑
建議的內容
適當的狀況下，連結至教學課程，包括子頁面
節點 4.1：使用 pip 安裝第一個元件¶
頁面宗旨
協助新的 pip 使用者開始使用 pip
建議內容：分步教學課程（可能分為數個頁面），內容包括
使用命令列
安裝 pip（或檢查 pip 是否已安裝）
建立/啟用虛擬環境（使用 venv 並說明其他替代方案）
安裝元件
顯示元件安裝位置
停用/重新啟用虛擬環境
解除安裝元件
節點 4.2：進階教學課程 - 在代理伺服器後方使用 pip¶
頁面宗旨
協助進階 pip 使用者達成特定目標
建議的內容
使用 pip 在代理伺服器後方運作的分步教學課程
附註：其他進階教學課程會由團隊識別或社群提出要求後新增。
5.0：使用 pip¶
頁面宗旨
提供使用者手冊和參考手冊的入門途徑
建議的內容
連結至使用者手冊中的每個主題
連結至參考手冊
5.1：使用者手冊¶
頁面宗旨
為使用者提供有關 pip 主要功能的具體詳細的說明
建議內容：將目前的使用者指南細分成不同的頁面，或按主題連結頁面。建議的順序
執行 pip
安裝套件
解除安裝套件
使用需求檔案重建環境
小標題：「釘選的版本號碼」
小標題：「雜湊檢查模式」
列出套件
搜尋套件
從本地套件進行安裝
從 Wheel 進行安裝
Wheel 組合
「僅在需要時」進行遞迴升級
組態
使用者安裝
指令完成
基本驗證憑證
使用代理伺服器（包含前往教學課程的連結）
限制檔案
從程式使用 pip
每個頁面應盡可能包含
用於解決問題、常見陷阱和邊緣使用案例的「提示與訣竅」
「疑難排解」資訊，適用的話，應連結至節點 6.2 的內容（「疑難排解錯誤訊息」）
「請參閱」，連結至外部資源（例如，堆疊溢出問題、留言板上的有用主題、部落格文章等）
請注意：下列內容應移至
修正衝突的依存關係（移至節點 6.2 -「疑難排解錯誤訊息」）
依存關係解析回溯（移至節點 6.2 -「疑難排解錯誤訊息」）
pip 依存關係解析器於 20.3 中的變更（移至節點 7.0 -「新聞、變更記錄和路線圖」）
5.2：參考指南¶
頁面宗旨
說明 pip 的 CLI
建議的內容
https://pip.dev.org.tw/en/stable/reference/
6.0：說明¶
頁面宗旨
提供一個起點供使用者找到他們有關 pip 的問題解答
建議的內容
連結至
6.1「常見問題集」
6.2「疑難排解錯誤訊息」
6.3「尋找更多說明」
6.1：常見問題集¶
頁面宗旨
回答常見的 pip 問題或搜尋字詞
建議的內容
pip 與 pip3 之間的差別是什麼？
pip 在哪裡安裝套件？
我如何檢查 pip 的版本？
我如何將 pip 新增至我的路徑中？
pip 安裝在哪裡？
pip 代表什麼意思？
請參閱堆疊溢出中的熱門問題以取得更多範例。
6.2：疑難排解錯誤訊息¶
頁面宗旨
協助 pip 使用者在使用 pip 時遇到錯誤時解決他們的問題。
建議內容：針對每一個（常見）錯誤訊息
說明發生了什麼事
說明為什麼會發生
說明使用者可以做什麼來解決問題
6.3：尋找更多協助¶
頁面宗旨
如果使用者在 pip 文件中找不到所需的資訊，請指引他們至其他資源
建議的內容
請參閱取得協助
7.0：新聞、變更日誌和路線圖¶
頁面宗旨
分享有關下列資訊
對 pip 的最新變更
對 pip 的即將到來變更
改善 pip 的構想，特別強調對資金的具體需求
建議的內容
有關 pip 的 PSF 部落格文章連結
前往可資助的包裝改善連結
8.0：貢獻¶
頁面宗旨
鼓勵新人對 pip 專案做出貢獻
展示專案對不同類型的貢獻所重視的價值，例如不僅限於開發
對過去和現在的貢獻者表示感謝
建議的內容
簡介 pip 作為一個開源專案
貢獻者行為守則
感謝獲得重視的不同類型貢獻
貢獻者名單，包含 pip 維護人員
8.1：開發¶
頁面宗旨
協助想為 pip 程式碼做出貢獻的人們
建議的內容
https://pip.dev.org.tw/en/stable/development/
8.2：使用者體驗設計¶
頁面宗旨
協助想為 pip 提供使用者體驗（研究或設計）貢獻的人們
與 pip 團隊分享使用者體驗知識和研究結果
建議的內容
使用者體驗指南，以及他們如何應用在 pip 專案中
目前的使用者體驗計畫（例如開放式調查、訪談時段等）
先前的研究和成果，包含使用者體驗元素（例如角色）
8.3：文件¶
頁面宗旨
協助想為 pip 文件做出貢獻的人們
分享與 pip 文件相關的先前研究和建議
建議的內容
這份指南
撰寫風格指南/術語表 - 查看倉庫文件作為示範。
未來的研究建議¶
為了持續改善 pip 的文件，我們建議
對 pip 使用者執行卡片分類以建立符合理想的排列順序和頁面群組
定期檢閱文件分析資料，了解哪些頁面最多/最少人造訪
定期檢閱 Stack Overflow 以找出常見問答題（FAQ）的問題
在使用者瀏覽文件網站時，建立機制收集使用者回饋