pip ドキュメントの改善¶

問題¶

公式 pip ドキュメントがユーザーの pip の問題解決に役立つかどうかを確認し、ドキュメントのコンテンツと構造を改善する方法を特定することを目的としています。

推奨事項へスキップ

調査¶

インタビュー¶

pip ユーザーを対象に、ドキュメントに関するインタビューを実施しました。インタビューでは、次の点について質問しました。

pip 使用中に経験した問題とその解決方法（使用した情報源に焦点を当てて）
pip のドキュメントの評価と、ドキュメントをより役立つものにするための改善点
(他のプロジェクトや言語からの)どのようなドキュメントが価値があり、その理由

アンケート¶

2つのアンケートを通じてドキュメントに関するフィードバックを収集しました。

pip ユーザーのプロファイリングを行ったアンケートでは、「pip のヘルプを得るための理想的な方法は？」という質問をしました。
pip のドキュメントに特化したアンケートも公開しました。

Screenshot of survey

キーワード調査¶

キーワード調査ツールを使用して、人々が検索エンジンを使用して pip の問題をトラブルシューティングする際に使用する単語（「キーワード」）を理解しました。

その他の調査方法¶

また、

pip の問題解決の経験を記録するダイアリー調査への参加者を募集しました。残念ながら、コミュニティからの関心の低さのため、これは完了しませんでした。
pip ドキュメントサイトへのユーザーフィードバックを求めました：残念ながら、この取り組みでは有益なフィードバックは得られませんでした。
pip ドキュメントに分析機能をインストールしました。マージされ、有用なデータを提供し始めるのを待っています。

結果¶

合計で、

pip のドキュメントに関するユーザーインタビューを 5 件実施しました。
「pip のヘルプを得るための理想的な方法は？」という質問に対して 141 件の回答を受け取りました。
ドキュメントに関するアンケートに対して 159 件の回答を受け取りました。

一般的に、pip のドキュメントはコミュニティで十分に活用されておらず、多くのユーザーはその存在を知りません。代わりに、ほとんどのユーザーは pip の問題を解決するために一般的なツール（Google、Stack Overflow）に頼っています。

「pip を使用していて問題が発生した場合、どうしますか？」という質問（複数選択可）に対する回答：

81.9% の回答者が Google で検索しました。
56.9% の回答者が Stack Overflow で検索または質問しました。
33.8% の回答者がコマンドラインから pip のヘルプを使用しました。
25.6% の回答者が pip ドキュメントを参照しました。
20.6% の回答者が Python パッケージングユーザーガイドを参照しました。
8.1% の回答者がフォーラム、コミュニティボード、またはチャットチャンネルで質問しました。

screenshot of survey results

アンケートの結果に基づくと、ユーザーは pip のドキュメントを

役に立たないよりもわずかに役に立つと感じています。
分かりにくいよりもわずかに分かりやすいと感じています。
意見が不足していると感じています。

アンケートとユーザーインタビューの両方から得られた一般的なフィードバックには、以下が含まれます。

ドキュメントの検索エンジンの検索結果でのパフォーマンスが悪い。
スタイルとレイアウトが古くなっている（注：このフィードバックは新しいテーマが展開される前に収集されました）。
一般的な問題の解決方法や特定の目標の達成方法に関するガイダンス/例が不十分である。
ドキュメントの情報アーキテクチャがナビゲートしにくい（ユーザーガイドの単一構造が問題である）ため、最も有用なコンテンツが優先されていない。
ユーザーの状況（例：使用しているオペレーティングシステム）に固有の指示を増やすべきである。
ドキュメントの範囲が不明確である。
ドキュメントは、pip が他のパッケージングツールのエコシステム内で存在することを認識する必要がある。
“There should be one-- and preferably only one --obvious way to do it.” - つまり、ドキュメントはより強力な推奨事項を提供する必要がある。

一部のユーザーはビデオが役立つと述べていますが、ビデオが長すぎる、または pip を使用して経験する種類の問題には不適切であると述べたユーザーの方が多い。

一部のユーザーは、対面でのサポート、フォーラム、またはチャットが役立つと述べており、既存のサポート/コミュニティチャネルを知らないユーザーも多い。

いくつかのユーザーは、pip のエラーメッセージを改善することで、より良いドキュメントの必要性を減らすことができるとも指摘しました。

キーワード調査から、「pip について」、「pip のインストール」、「pip のアンインストール」、「pip の更新」、「pip の使用」、「エラー」、「その他」の 7 つのクエリタイプを特定しました。

キーワード調査の結果を参照してください

pip について¶

pip とは何ですか
Python での pip とは何ですか
pip (Python) とは何ですか
pip の意味は何ですか
pip の略は何ですか
pip (Python) の略は何ですか
pip の意味

pip のインストール¶

pip を入手する
pip を Python にインストールする
pip をインストールする
pip のインストール
pip を Python にインストールする方法
pip をインストールする方法
pip をダウンロードする方法
pip を入手する方法
pip がインストールされているかどうかを確認する方法
Mac に pip をインストールする
Mac に pip をインストールする方法
Mac に pip をインストールする
Linux に pip をインストールする
Linux に pip をインストールする方法
Linux に pip をインストールする方法
Ubuntu に pip をインストールする方法
Ubuntu に pip をインストールする方法
Ubuntu に pip をインストールする
Ubuntu で pip をインストールする
Windows の pip
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 update
pip upgrade
pip をアップグレードする
Windows で pip をアップグレードする方法

pip の使用¶

pip の使用方法
pip install の使用方法
pip install の使用方法
pip (Python) の使用方法
pip でインストールする方法
pip を実行する方法
Python での pip の使用方法
pip install requirements.txt
pip requirements.txt
pip freeze
pip update package
pip install 特定のバージョン
pip upgrade package
pip uninstall package

エラー¶

no module named pip
pip コマンドが見つかりません
pip が認識されません
‘pip’ は内部コマンドまたは外部コマンド、操作可能なプログラムまたはバッチファイルとして認識されていません。
-bash: pip: command not found
pip は内部コマンドまたは外部コマンドとして認識されません
pip install 構文エラー

その他¶

pipをパスに追加する方法
pipのバージョンを確認する方法
pipの動作メカニズム
pipはパッケージをどこにインストールするか
pipとpip3の違い
pipのインストール場所

「pipのインストール」に関するクエリが非常に多いことから、現在のインストールに関するドキュメントを改善し、ユーザーが自身のオペレーティングシステムに固有の解決策を探せるようにする必要があることが強く示唆されています。

「pipについて」というクエリも、初心者にとって、pipの基本（pipとは何か、そしてそれが何をするのかなど）をよりよく説明したドキュメントが役立つことを示唆しています。

推奨事項¶

調査に基づき、pipチームに以下のことを推奨します。

ドキュメントの構造を見直す
- 一枚岩のページを、適切なメタタグを付けた異なる主題に関するスタンドアロンページに分割します。これにより、pipの問題のトラブルシューティングにGoogleを使用するユーザーの81.9％にとって、ドキュメントが検索結果の上位に表示されるようになります。
- 最も使用頻度の高い機能を優先する（ガイダンスについては、「機能を購入する」の結果を参照してください）
一般的な質問に対処し、エラーメッセージを説明し、ユーザーがさらにヘルプを見つけられる場所を伝えるトラブルシューティングセクションをドキュメントに追加する
pipのPythonパッケージエコシステムにおける役割に関するコンテキストをさらに提供する
- pipを使用するためにユーザーが理解する必要があるパッケージングの概念を紹介する
- パッケージエコシステム内でのpipの役割/範囲を説明する
- pipを他のツールと比較する
新しいpipユーザーがpipの最も基本的な機能を使用するために必要なことをすべて学習できる、初心者向けのガイドを作成します。これには、pipの範囲外の概念（ターミナルを開いて使用する方法、仮想環境を設定する方法など）に対処し、ユーザーの成功を妨げる可能性のある問題に対処する必要があります。
各ページに（適切な場合は）、以下のセクションを追加する
- 「ヒントとコツ」- 知っておくべきこと/注意点
- 「トラブルシューティング」-考えられるエラーメッセージと推奨される解決策。適切な場合は、トラブルシューティングセクションの内容へのリンクを含める。
- 「関連項目」（外部リソースへのリンク-例：役立つStack Overflowの質問、ブログ記事など）
一般的に、以下の内容のコンテンツを作成する
- 意見のあるコンテンツにする。ほとんどの場合に有効な解決策を優先し、「ヒントとコツ」、「トラブルシューティング」、「関連項目」のコンテンツで、考えられるエッジケースと回避策を指摘する
- 検索結果の表示頻度を高めるためにキーワードを使用する
- 異なるコンテキスト（例：Windows、Linux、macOSのユーザー）の指示を提供する
- packaging.python.orgを含む外部ソースとの相互リンクを増やす

提案されたサイトマップ¶

上記のユーザーからの入力に基づき、上記の推奨事項に従ってpipのドキュメントの再開発をガイドするために、提案されたサイトマップ（リンクをクリックすると、より大きなフォーマットの画像が開きます）を作成しました。

sitemap. for details see summary below

このサイトマップに関する注記を参照してください

ノード1.0：クイックリファレンス¶

ページの目的

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.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の実行
パッケージのインストール
パッケージのアンインストール
要件ファイルを使用した環境の再現
- 小見出し：「固定バージョン番号」
- 小見出し：「ハッシュチェックモード」
パッケージの一覧表示
パッケージの検索
ローカルパッケージからのインストール
Wheelsからのインストール
Wheelバンドル
「必要に応じてのみ」再帰的アップグレード
設定
ユーザーインストール
コマンド補完
基本認証資格情報
プロキシサーバーの使用（チュートリアルへのリンクを含む）
制約ファイル
プログラムからのpipの使用

可能な限り、各ページに以下を含める

回避策、一般的な_注意点_、エッジユースケースに関する「ヒントとコツ」
該当する場合は、ノード6.2（「エラーメッセージのトラブルシューティング」）の内容へのリンクを含む「トラブルシューティング」情報
外部リソース（例：Stack Overflowの質問、メッセージボードの役立つスレッド、ブログ投稿など）へのリンクを含む「関連項目」

注：以下のコンテンツを移動する必要があります。

競合する依存関係の修正（ノード6.2「エラーメッセージのトラブルシューティング」に移動）
依存関係の解決におけるバックトラッキング（ノード6.2「エラーメッセージのトラブルシューティング」に移動）
20.3でのpip依存関係解決の変更（ノード7.0「ニュース、変更ログ、ロードマップ」に移動）

5.2：リファレンスガイド¶

ページの目的

pipのCLIを文書化する

提案されたコンテンツ

https://pip.dokyumento.jp/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改善のためのアイデア（特に、資金援助が必要な箇所を強調）

提案されたコンテンツ

8.0: コントリビューション¶

ページの目的

pipプロジェクトへの新規コントリビューターの参加を促進します。
開発だけでなく、様々な貢献の種類（例えば、ドキュメント作成など）がプロジェクトで高く評価されていることを示します。
過去および現在の貢献者に感謝を示します。

提案されたコンテンツ

オープンソースプロジェクトとしてのpipの紹介
コントリビューター向け行動規範
高く評価される様々な貢献の種類の認識
pipメンテナーを含む、コントリビューターのクレジットリスト

8.1: 開発¶

ページの目的

pipへのコードコントリビューションを希望する人を迎え入れます。

提案されたコンテンツ

https://pip.dokyumento.jp/en/stable/development/

8.2: UXデザイン¶

ページの目的

pipへのUX（リサーチまたはデザイン）コントリビューションを希望する人を迎え入れます。
pipチームとUXに関する知識や調査結果を共有します。

提案されたコンテンツ

UXガイドラインと、それらがpipプロジェクトにどのように適用されるか
現在のUXイニシアチブ（例：公開調査、インタビュー枠など）
以前の調査と結果、UX成果物（例：ペルソナ）を含む

8.3: ドキュメント¶

ページの目的

pipのドキュメントへのコントリビューションを希望する人を迎え入れます。
以前の調査と、pipのドキュメントに関する推奨事項を共有します。

提案されたコンテンツ

このガイド
ライティングスタイルガイド/用語集 - 例としてWarehouseドキュメントを参照してください。

今後の調査提案¶

pipのドキュメントを継続的に改善するために、以下を提案します。

pipユーザーを対象としたカードソーティングを実施し、ページの理想的な順序とグループ化を確立する。
ドキュメント分析を定期的にレビューし、最も/最もアクセスされていないページを理解する。
Stack Overflowを定期的にレビューし、FAQの質問を特定する。
ユーザーがドキュメントサイトにいる間にユーザーフィードバックを収集するためのメカニズムを構築する。