McSinyx
/
pip
mirror of https://github.com/pypa/pip
1
1
Fork 0
Code Issues Releases Activity

Formatting updates

This commit is contained in:
Nicole Harris 2023-08-20 10:26:39 +01:00
parent 0179718a94
commit 7915302794
2 changed files with 222 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

345
docs/html/ux-research-design/2020-research-outputs/improving-pips-documentation.md
View File

@ -11,6 +11,7 @@ We want to establish whether or not the [official pip documentation](https://pip
### Interviews
We conducted interviews with pip users specifically discussing documentation. During these interviews we asked about:
- Problems they had experienced while using pip, and how they solved them (with a focus on what information sources they used)
- How they rate pip's documentation, and what we could do to make the docs more useful
- What documentation (from other projects or languages) they find valuable, and why
@ -34,13 +35,14 @@ We also:
1. Asked for volunteers to participate in a diary study, documenting their experience solving pip problems. Unfortunately this was not completed due to lack of interest from the community.
2. Asked for user feedback on the pip documentation site:
![TODO](https://i.imgur.com/WJVjl8N.png)
Unfortunatly, we did not gather any useful feedback via this effort
![TODO](https://i.imgur.com/WJVjl8N.png)
Unfortunatly, we did not gather any useful feedback via this effort
3. [Installed analytics on the pip docs](https://github.com/pypa/pip/pull/9146). We are waiting for this to be merged and start providing useful data.
## Response / results
In total, we:
- Conducted 5 user interviews about pip's documentation
- Received 141 responses to the question "What would be your ideal way of getting help with pip?"
- Received 159 responses to the documentation survey
@ -59,11 +61,13 @@ In response to the question "When you have a problem using pip, what do you do?"
![TODO](https://i.imgur.com/qlt1b4n.png)
Based on survey results, users find pip's docs:
- Marginally more useful than not useful
- Marginally more clear than unclear
- Not opinionated enough
Common feedback that emerged from both surveys and user interviews includes:
- The documentation performs poorly in search engine results
- The style and layout is dated (note: this feedback was collected before the [new theme was deployed](https://github.com/pypa/pip/pull/9012))
- There is not enough guidance/examples on how to resolve common problems, or achieve specific goals
@ -83,96 +87,97 @@ From our keyword research we identified seven _query types_: "about pip", "insta
<details><summary> See keyword research results</summary>
#### About pip
### About pip
* what is pip
* what is pip in python
* what is pip python
* what does pip mean
* what does pip stand for
* what does pip stand for python
* pip meaning
- what is pip
- what is pip in python
- what is pip python
- what does pip mean
- what does pip stand for
- what does pip stand for python
- pip meaning
#### Install pip
### Install pip
* get pip
* python install pip
* install pip
* installing pip
* how to install pip python
* how to install pip
* how to download pip
* how to get pip
* how to check if pip is installed
* install pip mac
* how to install pip on mac
* install pip on mac
* install pip linux
* how to install pip linux
* how to install pip on linux
* how to install pip in ubuntu
* how to install pip ubuntu
* install pip ubuntu
* ubuntu install pip
* pip windows
* install pip windows
* pip install windows
* how to install pip windows
* how to install pip in windows
* how to install pip on windows
* how to pip install on windows
* how to install pip on windows 10
* how to run pip on windows
- get pip
- python install pip
- install pip
- installing pip
- how to install pip python
- how to install pip
- how to download pip
- how to get pip
- how to check if pip is installed
- install pip mac
- how to install pip on mac
- install pip on mac
- install pip linux
- how to install pip linux
- how to install pip on linux
- how to install pip in ubuntu
- how to install pip ubuntu
- install pip ubuntu
- ubuntu install pip
- pip windows
- install pip windows
- pip install windows
- how to install pip windows
- how to install pip in windows
- how to install pip on windows
- how to pip install on windows
- how to install pip on windows 10
- how to run pip on windows
#### Uninstall pip
### Uninstall pip
* how to uninstall pip
* uninstall pip
* pip uninstall
- how to uninstall pip
- uninstall pip
- pip uninstall
#### Update pip
* how to update pip
* how to upgrade pip
* pip update
* pip upgrade
* upgrade pip
* how to upgrade pip on windows
### Update pip
#### Using pip
- how to update pip
- how to upgrade pip
- pip update
- pip upgrade
- upgrade pip
- how to upgrade pip on windows
* how to use pip
* how to use pip install
* how to pip install
* how to use pip python
* how to install with pip
* how to run pip
* python how to use pip
* pip install requirements.txt
* pip requirements.txt
* pip freeze
* pip update package
* pip install specific version
* pip upgrade package
* pip uninstall package
### Using pip
#### Errors
- how to use pip
- how to use pip install
- how to pip install
- how to use pip python
- how to install with pip
- how to run pip
- python how to use pip
- pip install requirements.txt
- pip requirements.txt
- pip freeze
- pip update package
- pip install specific version
- pip upgrade package
- pip uninstall package
* no module named pip
* pip command not found
* pip is not recognized
* 'pip' is not recognized as an internal or external command, operable program or batch file.
* -bash: pip: command not found
* pip is not recognized as an internal or external command
* pip install invalid syntax
### Errors
#### Other
- no module named pip
- pip command not found
- pip is not recognized
- 'pip' is not recognized as an internal or external command, operable program or batch file.
- -bash: pip: command not found
- pip is not recognized as an internal or external command
- pip install invalid syntax
* how to add pip to path
* how to check pip version
* how does pip work
* where does pip install packages
* pip vs pip3
* where is pip installed
### Other
- how to add pip to path
- how to check pip version
- how does pip work
- where does pip install packages
- pip vs pip3
- where is pip installed
</details>
<br/>
@ -188,21 +193,21 @@ Based on our research, we recommend that the pip team:
- Revise the structure of the documentation:
- Break monolithic pages into standalone pages on different subjects, with appropriate meta tags. This will help the docs appear higher in search results for the 81.9% of users who use Google to troubleshoot their pip problems.
- Prioritise most used features (see "[buy a feature](TODO)" results for guidance)
- Add a "troubleshooting" section to the documentation that addresses common questions, explains error messages and tells users where they can find more help
- Add a "troubleshooting" section to the documentation that addresses common questions, explains error messages and tells users where they can find more help
- Provide more context about pip's role in the Python packaging ecosystem by:
- Introducing packaging concepts that users need to understand in order to use pip
- Explaining pip's role/scope within the packaging ecosystem
- Comparing pip to other tools
- Introducing packaging concepts that users need to understand in order to use pip
- Explaining pip's role/scope within the packaging ecosystem
- Comparing pip to other tools
- Develop a beginner's guide that walks new pip users through everything they need to know to use pip's most basic functionality. This should include addressing concepts outside of pip's scope (e.g. how to open and use a terminal, how to set up a virtual environment), that may block users from being successful
- For each page, (where appropriate), add sections for:
- "tips and tricks" - things to know / gotchas
- "troubleshooting" - possible error messages and recommended solutions. Where appropriate, this should link to content in the troubleshooting section.
- "see also" (links to external resources - e.g. useful stack overflow questions, blog articles, etc.)
- "tips and tricks" - things to know / gotchas
- "troubleshooting" - possible error messages and recommended solutions. Where appropriate, this should link to content in the troubleshooting section.
- "see also" (links to external resources - e.g. useful stack overflow questions, blog articles, etc.)
- In general, write content that:
- Is opinionated. Prioritize solutions that will work in the majority of cases, while pointing to possible edge cases and workarounds in "tips and tricks", "troubleshooting" and "see also" content
- Uses keywords to increase search results visibility
- Provides instructions for different contexts - e.g. for users on Windows, Linux, MacOSX
- Increases interlinking with external sources, including packaging.python.org
- Is opinionated. Prioritize solutions that will work in the majority of cases, while pointing to possible edge cases and workarounds in "tips and tricks", "troubleshooting" and "see also" content
- Uses keywords to increase search results visibility
- Provides instructions for different contexts - e.g. for users on Windows, Linux, MacOSX
- Increases interlinking with external sources, including packaging.python.org
### Suggested site map
@ -214,21 +219,26 @@ Based on the above user input, we have developed a proposed [site map](https://i
#### Node 1.0: Quick reference
*Page purpose:*
_Page purpose:_
- To give pip users a quick overview of how to install pip, and use pip's main functionality
- To link to other (more detailed) areas of the documentation
*Suggested content:*
- Quick installation guide, including how to use a virtual environment. This is necessary for user who want to install more than one Python project on their machine.
_Suggested content:_
- Quick installation guide, including how to use a virtual environment. This is necessary for user who want to install more than one Python project on their machine.
- Common commands / tasks (based on [buy a feature](TODO) data)
---
#### Node 2.0: About pip
*Page purpose:*
_Page purpose:_
- To introduce pip to new users
*Suggested content:*
_Suggested content:_
- Introduce pip as a command line program
- Explain what the command line is and how to use it in different operating systems
- Explain what pip is/does, and what it stands for
@ -236,10 +246,13 @@ Based on the above user input, we have developed a proposed [site map](https://i
- Explain pip's scope (e.g. to install and uninstall packages) and link to other tools (node 2.2)
#### Node 2.1: Packaging concepts
*Page purpose:*
_Page purpose:_
- To introduce packaging concepts for new pip users
*Suggested content:*
_Suggested content:_
- What is a package?
- What types of packages are there? e.g. file types
- What is package versioning / what are requirement specifiers? (note: talk about potential dependency conflicts here)
@ -250,37 +263,51 @@ Based on the above user input, we have developed a proposed [site map](https://i
- Link to node 2.2 ("pip vs other packaging tools")
#### Node 2.2: pip vs other packaging tools
*Page purpose:*
_Page purpose:_
- To compare pip to other tools with the same scope
- To highlight that pip exists within a _packaging ecosystem_ and link to other packaging tools
*Suggested content:*
_Suggested content:_
- Compare pip to other installation tools - e.g. poetry, pipenv, conda. What are the features, pros and cons of each? Why do packaging users choose one over the other?
- Briefly introduce other packaging projects. Link to https://packaging.python.org/key_projects/
---
#### Node 3.0: Installing pip
*Page purpose:*
_Page purpose:_
- To help pip users install pip
*Suggested content:*
_Suggested content:_
- Refactor current page, emphasising pathways for different operating systems
- Add "tips and tricks", "troubleshooting" and "see also" (link to external resources) sections to provide additional help
---
#### Node 4.0: Tutorials
*Page purpose:*
_Page purpose:_
- To provide a jumping off place into pip's tutorials
*Suggested content:*
_Suggested content:_
- Link to tutorials, including sub pages, where appropriate
#### Node 4.1: Using pip to install your first package
*Page purpose:*
_Page purpose:_
- To help new pip users get started with pip
*Suggested content:*
_Suggested content:_
Step by step tutorial (possibly broken into several pages) that covers:
- Using the command line
- Installing pip (or checking pip is installed)
- Creating/activating a virtual env (use venv for this, but point to alternatives)
@ -290,29 +317,39 @@ Step by step tutorial (possibly broken into several pages) that covers:
- Uninstalling a package
#### Node 4.2: Advanced tutorial - using pip behind a proxy
*Page purpose:*
_Page purpose:_
- To help advanced pip users achieve specific goals
*Suggested content:*
_Suggested content:_
- Step by step tutorial for using pip behind a proxy
NB: other advanced tutorials should be added as identified by the team and/or requested by the community.
---
#### 5.0: Using pip
*Page purpose:*
_Page purpose:_
- To provide a jumping off point for the user guide and reference guide
*Suggested content:*
_Suggested content:_
- Link to each subject in the user guide
- Link to reference guide
#### 5.1: User guide
*Page purpose:*
_Page purpose:_
- To provide users with specific detailed instructions on pip's key features
*Suggested content:*
_Suggested content:_
Break down current user guide into separate pages, or pages linked by subject. Suggested order:
- Running pip
- Installing Packages
- Uninstalling Packages
@ -334,38 +371,50 @@ Break down current user guide into separate pages, or pages linked by subject. S
- Using pip from your program
Where possible, each page should include:
- "tips and tricks" for workarounds, common _gotchas_ and edge use cases
- "troubleshooting" information, linking to content in node 6.2 ("Troubleshooting error messages") where applicable
- "see also", linking to external resources (e.g. stack overflow questions, useful threads on message boards, blogs posts, etc.
Note: the following content should be moved:
- Fixing conflicting dependencies (move to node 6.2 - "Troubleshooting error messages")
- Dependency resolution backtracking (move to node 6.2 - "Troubleshooting error messages")
- Changes to the pip dependency resolver in 20.3 (move to node 7.0 - "News, changelog and roadmap")
#### 5.2: Reference guide
*Page purpose:*
_Page purpose:_
- To document pip's CLI
*Suggested content:*
_Suggested content:_
- https://pip.pypa.io/en/stable/reference/
---
#### 6.0: Help
*Page purpose:*
_Page purpose:_
- To provide a jumping off place for users to find answers to their pip questions
*Suggested content:*
_Suggested content:_
- Links to
- 6.1 "FAQs"
- 6.2 "Troubleshooting error messages"
- 6.3 "Finding more help"
- 6.1 "FAQs"
- 6.2 "Troubleshooting error messages"
- 6.3 "Finding more help"
#### 6.1: FAQs
*Page purpose:*
_Page purpose:_
- To answer common pip questions / search terms
*Suggested content:*
_Suggested content:_
- What is the difference between pip and pip3?
- Where does pip install packages?
- How can I check pip's version?
@ -376,11 +425,14 @@ Note: the following content should be moved:
See [keyword research](TODO) and [popular questions on Stack Overflow](https://stackoverflow.com/search?q=pip&s=ec4ee117-277a-4c5d-a3f5-c921ca6c5da6) for more examples.
#### 6.2: Troubleshooting error messages
*Page purpose:*
_Page purpose:_
- To help pip users solve their problem when they experience an error using pip
*Suggested content:*
_Suggested content:_
For each (common) error message:
- Explain what happened
- Explain why it happened
- Explain what the user can do to resolve the problem
@ -389,67 +441,88 @@ Note: the [ResolutionImpossible](https://pip.pypa.io/en/stable/user_guide/#fixin
documentation should both be moved here.
#### 6.3: Finding more help
*Page purpose:*
_Page purpose:_
- To point pip users to other resources if they cannot find the information they need within the pip documentation
*Suggested content:*
_Suggested content:_
- See [getting help](https://pip.pypa.io/en/stable/user_guide/#getting-help)
---
#### 7.0: News, changelog and roadmap
*Page purpose:*
_Page purpose:_
- To share information about:
- Recent changes to pip
- Upcoming changes to pip
- Ideas for improving pip, specifically highlighting where funding would be useful
*Suggested content:*
_Suggested content:_
- [Changes to the pip dependency resolver in 20.3 (2020)](https://pip.pypa.io/en/stable/user_guide/#changes-to-the-pip-dependency-resolver-in-20-3-2020)
- Links to PSF blog posts about pip
- Link to [fundable packaging improvements](https://github.com/psf/fundable-packaging-improvements/blob/master/FUNDABLES.md)
---
#### 8.0: Contributing
*Page purpose:*
_Page purpose:_
- To encourage new people to contribute to the pip project
- To demonstrate that the project values different *types* of contributions, e.g. not just development
- To demonstrate that the project values different _types_ of contributions, e.g. not just development
- To recognise past and current contributors
*Suggested content:*
_Suggested content:_
- Introduction to pip as an open source project
- Contributors code of conduct
- Recognition of the different types of contributions that are valued
- Credit list of contributors, including pip maintainers
#### 8.1: Development
*Page purpose:*
_Page purpose:_
- To onboard people who want to contribute code to pip
*Suggested content:*
_Suggested content:_
- https://pip.pypa.io/en/stable/development/
#### 8.2: UX design
*Page purpose:*
_Page purpose:_
- To onboard people who want to contribute UX (research or design) to pip
- To share UX knowledge and research results with the pip team
*Suggested content:*
_Suggested content:_
- UX guidelines, and how they apply to the pip project
- Current UX initiatives (e.g. open surveys, interview slots, etc.)
- Previous research and results, including UX artifacts (e.g. personas)
#### 8.3: Documentation
*Page purpose:*
_Page purpose:_
- To onboard people who want to contribute to pip's docs
- To share previous research and recommendataions related to pip's docs
*Suggested content:*
_Suggested content:_
- This guide
- Writing styleguide / glossary of terms - see the [Warehouse documentation](https://warehouse.readthedocs.io/ui-principles.html#write-clearly-with-consistent-style-and-terminology) for an example.
</details>
## Future research suggestions
To continue to improve pip's documentation, we suggest:
- Conducting [card sorting](https://www.nngroup.com/articles/card-sorting-definition/) with pip users to establish the ideal order and grouping of pages

26
docs/html/ux-research-design/research-results.md
View File

@ -339,18 +339,18 @@ We are currently looking for volunteers to take recommendations made by the UX t
</div>
```{toctree}
about-our-users
ci-cd
improving-pip-documentation
mental-models
override-conflicting-dependencies
personas
pip-force-reinstall
pip-logo
pip-search
pip-upgrade-conflict
prioritizing-features
users-and-security
/2020-research-outputs/about-our-users
/2020-research-outputs/ci-cd
/2020-research-outputs/improving-pip-documentation
/2020-research-outputs/mental-models
/2020-research-outputs/override-conflicting-dependencies
/2020-research-outputs/personas
/2020-research-outputs/pip-force-reinstall
/2020-research-outputs/pip-logo
/2020-research-outputs/pip-search
/2020-research-outputs/pip-upgrade-conflict
/2020-research-outputs/prioritizing-features
/2020-research-outputs/users-and-security
```
## Read More
@ -364,7 +364,7 @@ users-and-security
- [pip UX studies: response data (blog, March 2020)](https://www.ei8fdb.org/thoughts/2020/03/pip-ux-studies-response-data/)
- Other PyPA UX work:
- [PyPI User Research (blog, July 2018)](https://whoisnicoleharris.com/2018/07/22/pypi-user-research.html)
- [Warehouse - The Future of PyPI](https://whoisnicoleharris.com/warehouse/)<span style="text-decoration:underline;"> (overview)</span>
- [Warehouse - The Future of PyPI](https://whoisnicoleharris.com/warehouse/)
- [Accessibility on Warehouse (PyPI) (blog, May 2018)](https://whoisnicoleharris.com/2018/05/17/warehouse-accessibility.html)
- [User Testing Warehouse (blog, Mar 2018)](https://whoisnicoleharris.com/2018/03/13/user-testing-warehouse.html)
- [Designing Warehouse - An Overview (blog, Dec 2015)](https://whoisnicoleharris.com/2015/12/31/designing-warehouse-an-overview.html)