改进 pip 的文档¶
问题¶
我们想要确定官方 pip 文档是否可以帮助用户解决他们的 pip 问题。我们还想确定对文档内容和结构的可能改进。
研究¶
访谈¶
我们对 pip 用户进行了访谈，专门讨论文档。在这些访谈中，我们询问了
他们在使用 pip 时遇到的问题以及如何解决这些问题（重点关注他们使用的信息来源）
他们如何评价 pip 的文档，以及我们可以做些什么来使文档更有用
他们认为哪些文档（来自其他项目或语言）很有价值，以及为什么
调查¶
我们通过两次调查收集了文档反馈
在我们对 pip 用户进行的调查中，我们询问了“您认为获得 pip 帮助的理想方式是什么？”
我们还发布了针对 pip 文档的调查
关键词研究¶
我们使用关键词研究工具来了解人们在使用搜索引擎排查 pip 问题时使用的词语（“关键词”）。
其他研究方法¶
我们还
邀请志愿者参与日记研究，记录他们解决 pip 问题的经历。不幸的是，由于社区缺乏兴趣，这项研究没有完成。
在 pip 文档网站上征求用户反馈：
不幸的是，我们没有通过这项工作收集到任何有用的反馈在 pip 文档上安装分析。我们正在等待它合并并开始提供有用的数据。
结果¶
总的来说，我们
对 pip 的文档进行了 5 次用户访谈
收到了 141 个关于“您认为获得 pip 帮助的理想方式是什么？”的问题回复
收到了 159 个关于文档的调查回复
总的来说，我们发现 pip 的文档在社区中使用率较低，许多用户不知道它的存在。相反，大多数用户转向常用的工具（谷歌、Stack Overflow）来解决他们的 pip 问题。
针对“当您在使用 pip 时遇到问题时，您会怎么做？”的问题（多选）
81.9% 的受访者使用谷歌搜索
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
什么是 python pip
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
pip 安装 windows
如何在 windows 上安装 pip
如何在 windows 上安装 pip
如何在 windows 上安装 pip
如何在 windows 上使用 pip 安装
如何在 windows 10 上安装 pip
如何在 windows 上运行 pip
卸载 pip¶
如何卸载 pip
卸载 pip
pip uninstall
更新 pip¶
如何更新 pip
如何升级 pip
pip update
pip upgrade
升级 pip
如何在 windows 上升级 pip
使用 pip¶
如何使用 pip
如何使用 pip install
如何使用 pip 安装
如何使用 python pip
如何使用 pip 安装
如何运行 pip
python 如何使用 pip
pip install requirements.txt
pip requirements.txt
pip freeze
pip update package
pip install specific version
pip upgrade package
pip uninstall package
错误¶
没有名为 pip 的模块
找不到 pip 命令
pip 未被识别
‘pip’ 未被识别为内部或外部命令、可操作程序或批处理文件。
-bash: pip: command not found
pip 未被识别为内部或外部命令
pip install 语法错误
其他¶
如何将 pip 添加到路径
如何检查 pip 版本
pip 如何工作
pip 将软件包安装在什么位置
pip 与 pip3
pip 安装在哪里
“安装 pip”查询的普遍性强烈表明，应该改进当前的安装文档，并且用户正在寻找针对其操作系统的解决方案。
“关于 pip”查询也表明，初学者将从更好地解释 pip 基础知识的文档中受益，例如 pip 是什么以及它做什么。
建议¶
根据我们的研究，我们建议 pip 团队
修改文档结构
将整体页面分解为不同主题的独立页面，并添加相应的元标签。这将有助于文档在搜索结果中排名更高，因为 81.9% 的用户使用谷歌来排查他们的 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/它做什么，以及它的含义
链接到打包概念（节点 2.1）
解释 pip 的范围（例如，安装和卸载包）并链接到其他工具（节点 2.2）
节点 2.1：打包概念¶
页面目的
向新的 pip 用户介绍打包概念
建议内容
什么是包？
有哪些类型的包？ 例如，文件类型
什么是包版本控制/什么是需求说明符？（注意：在这里讨论潜在的依赖冲突）
我从哪里获得包？
我应该如何控制包在我的系统上的安装方式（例如，virtualenv 和环境隔离）
如何重现环境/确保可重复性？（例如，需求文件）
关于安全性，我需要知道什么？（例如，哈希检查、PyPI 名称抢占）
链接到节点 2.2（“pip 与其他打包工具”）
节点 2.2：pip 与其他打包工具¶
页面目的
将 pip 与具有相同范围的其他工具进行比较
强调 pip 存在于一个打包生态系统中，并链接到其他打包工具
建议内容
将 pip 与其他安装工具进行比较 - 例如，poetry、pipenv、conda。 它们各自的功能、优缺点是什么？ 为什么打包用户选择其中一个而不是另一个？
简要介绍其他打包项目。 链接到 https://packaging.pythonlang.cn/key_projects/
节点 3.0：安装 pip¶
页面目的
帮助 pip 用户安装 pip
建议内容
重构当前页面，重点介绍不同操作系统的途径
添加“技巧和窍门”、“故障排除”和“另请参阅”（链接到外部资源）部分，以提供额外的帮助
节点 4.0：教程¶
页面目的
提供一个跳板，进入 pip 的教程
建议内容
链接到教程，包括子页面（在适当的情况下）
节点 4.1：使用 pip 安装第一个包¶
页面目的
帮助新的 pip 用户开始使用 pip
建议内容：分步教程（可能分成几个页面），涵盖以下内容：
使用命令行
安装 pip（或检查 pip 是否已安装）
创建/激活虚拟环境（为此使用 venv，但指向替代方案）
安装包
显示包的安装位置
停用/重新激活 virtualenv
卸载包
节点 4.2：高级教程 - 在代理后面使用 pip¶
页面目的
帮助高级 pip 用户实现特定目标
建议内容
在代理后面使用 pip 的分步教程
注意：应根据团队的识别或社区的请求添加其他高级教程。
5.0：使用 pip¶
页面目的
为用户指南和参考指南提供一个跳板
建议内容
链接到用户指南中的每个主题
链接到参考指南
5.1：用户指南¶
页面目的
向用户提供有关 pip 关键功能的特定详细说明
建议内容：将当前用户指南分解成单独的页面，或者通过主题链接的页面。 建议的顺序
运行 pip
安装包
卸载包
使用需求文件重建环境
小标题：“固定版本号”
小标题：“哈希检查模式”
列出包
搜索包
从本地包安装
从 Wheels 安装
Wheel 包
“仅在必要时”递归升级
配置
用户安装
命令完成
基本身份验证凭据
使用代理服务器（包括链接到教程）
约束文件
从您的程序中使用 pip
在可能的情况下，每个页面都应该包括
“技巧和窍门”，用于解决方法、常见的注意事项和边缘使用情况
“故障排除”信息，在适用情况下链接到节点 6.2（“故障排除错误消息”）中的内容
“另请参阅”，链接到外部资源（例如，Stack Overflow 问题、消息板上的有用主题、博客文章等）
注意：以下内容应移动
修复冲突的依赖项（移动到节点 6.2 - “故障排除错误消息”）
依赖关系解析回溯（移动到节点 6.2 - “故障排除错误消息”）
20.3 中 pip 依赖关系解析器的更改（移动到节点 7.0 - “新闻、变更日志和路线图”）
5.2：参考指南¶
页面目的
记录 pip 的 CLI
建议内容
https://pip.pythonlang.cn/en/stable/reference/
6.0：帮助¶
页面目的
为用户提供一个跳板，让他们找到有关 pip 问题的答案
建议内容
链接到
6.1“常见问题解答”
6.2“故障排除错误消息”
6.3“寻找更多帮助”
6.1：常见问题解答¶
页面目的
回答有关 pip 的常见问题/搜索词
建议内容
pip 和 pip3 有什么区别？
pip 在哪里安装包？
如何检查 pip 的版本？
如何将 pip 添加到我的路径？
pip 安装在哪里？
pip 代表什么？
请参阅 Stack Overflow 上的热门问题 以获取更多示例。
6.2：故障排除错误消息¶
页面目的
帮助 pip 用户在使用 pip 时遇到错误时解决他们的问题
建议内容：对于每个（常见）错误消息
解释发生了什么
解释为什么会发生
解释用户可以采取哪些措施来解决问题
注意：ResolutionImpossible 和 依赖关系解析回溯 文档都应移动到这里。
6.3：寻找更多帮助¶
页面目的
如果 pip 用户无法在 pip 文档中找到他们需要的信息，则将他们引导到其他资源
建议内容
请参阅 获取帮助
7.0：新闻、变更日志和路线图¶
页面目的
分享有关以下内容的信息：
pip 的最新变化
pip 的即将发生的更改
改进 pip 的想法，特别是突出显示哪里需要资金
建议内容
链接到 PSF 关于 pip 的博客文章
链接到 可资助的打包改进
8.0：贡献¶
页面目的
鼓励新人为 pip 项目做出贡献
展示项目重视不同类型的贡献，例如，不仅仅是开发
认可过去和现在的贡献者
建议内容
将 pip 作为开源项目介绍
贡献者行为准则
认可所重视的不同类型的贡献
贡献者名单，包括 pip 维护者
8.1：开发¶
页面目的
为想要为 pip 贡献代码的人提供入门指导
建议内容
https://pip.pythonlang.cn/en/stable/development/
8.2：UX 设计¶
页面目的
为想要为 pip 贡献 UX（研究或设计）的人提供入门指导
与 pip 团队分享 UX 知识和研究成果
建议内容
UX 指南以及它们如何应用于 pip 项目
当前的 UX 计划（例如，开放调查、面试时间段等）
以前的研究和结果，包括 UX 工件（例如，人物角色）
8.3：文档¶
页面目的
为想要为 pip 文档做出贡献的人提供入门指导
分享有关 pip 文档的先前研究和建议
建议内容
本指南
写作风格指南/术语表 - 请参阅 Warehouse 文档 以获取示例。
未来的研究建议¶
为了继续改进 pip 的文档，我们建议
与 pip 用户进行卡片排序，以确定页面的理想顺序和分组
定期审查文档分析，以了解访问量最大/最少的页面
定期审查 Stack Overflow 以识别常见问题解答中的问题
建立一个机制，在用户访问文档网站时收集用户反馈