diff --git a/docs/html/ux-research-design/research-results/improving-pips-documentation.md b/docs/html/ux-research-design/research-results/improving-pips-documentation.md index 3ae3330370f..e9398437d54 100644 --- a/docs/html/ux-research-design/research-results/improving-pips-documentation.md +++ b/docs/html/ux-research-design/research-results/improving-pips-documentation.md @@ -1,4 +1,4 @@ -# pip's documentation +# Improving pip's Documentation ## Problem @@ -23,7 +23,7 @@ We collected documentation feedback via two surveys: - In our survey that profiled pip users, we asked "What would be your ideal way of getting help with pip?" - We also published a survey specific to pip's docs: -![TODO](https://i.imgur.com/dtTnTQJ.png) +![Screenshot of survey](https://i.imgur.com/dtTnTQJ.png) ### Keyword research @@ -35,7 +35,7 @@ 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) + ![screenshot of user feedback mechanism on pip docs](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. @@ -58,7 +58,7 @@ In response to the question "When you have a problem using pip, what do you do?" - 20.6% of respondents go the the Python Packaging User Guide - 8.1% of respondents ask on a forum, community board, or chat channel -![TODO](https://i.imgur.com/qlt1b4n.png) +![screenshot of survey results](https://i.imgur.com/qlt1b4n.png) Based on survey results, users find pip's docs: @@ -192,7 +192,7 @@ 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) + - Prioritise most used features (see "[buy a feature]()" 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 - 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 @@ -213,7 +213,7 @@ Based on our research, we recommend that the pip team: Based on the above user input, we have developed a proposed [site map](https://i.imgur.com/UP5q09W.png) (link opens larger format image) to help guide the redevelopment of pip's documentation in line with the above recommendations. -![TODO](https://i.imgur.com/UP5q09W.png) +![sitemap. for details see summary below](https://i.imgur.com/UP5q09W.png)
See notes for this site map @@ -227,7 +227,7 @@ _Page purpose:_ _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) +- Common commands / tasks (based on [buy a feature](prioritizing-features) data) --- @@ -422,7 +422,7 @@ _Suggested content:_ - Where is pip installed? - What does pip stand for? -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. +See [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 diff --git a/docs/html/ux-research-design/research-results/index.md b/docs/html/ux-research-design/research-results/index.md index 2fda96c47a3..da5c9f2c289 100644 --- a/docs/html/ux-research-design/research-results/index.md +++ b/docs/html/ux-research-design/research-results/index.md @@ -8,12 +8,12 @@ mental-models users-and-security ci-cd personas -improving-pips-documentation prioritizing-features override-conflicting-dependencies pip-force-reinstall pip-search pip-upgrade-conflict +improving-pips-documentation ``` ## 2020 Research Synthesis @@ -201,12 +201,12 @@ mental-models users-and-security ci-cd personas -improving-pips-documentation prioritizing-features override-conflicting-dependencies pip-force-reinstall pip-search pip-upgrade-conflict +improving-pips-documentation ``` ## Read More diff --git a/docs/html/ux-research-design/research-results/override-conflicting-dependencies.md b/docs/html/ux-research-design/research-results/override-conflicting-dependencies.md index 564e58c845d..93ce442aff5 100644 --- a/docs/html/ux-research-design/research-results/override-conflicting-dependencies.md +++ b/docs/html/ux-research-design/research-results/override-conflicting-dependencies.md @@ -10,6 +10,8 @@ As a result, some users may feel that newer versions of pip are "broken" when pi For this reason, the pip team wanted to know if they should provide an override that allows users to install conflicting packages. +[Skip to recommendations](#recommendations) + ## Research We published a survey with the following introduction: diff --git a/docs/html/ux-research-design/research-results/pip-search.md b/docs/html/ux-research-design/research-results/pip-search.md index bf5765161b2..3cf1b5eb01f 100644 --- a/docs/html/ux-research-design/research-results/pip-search.md +++ b/docs/html/ux-research-design/research-results/pip-search.md @@ -4,6 +4,8 @@ By default, `pip search` searches packages on PyPI.org from the command line. However, the team are [considering removing it](https://github.com/pypa/pip/issues/5216), because they think it's not that useful and using too many resources on PyPI ([PyPI XMLRPC search has been disabled](https://status.python.org/incidents/grk0k7sz6zkp) because of abuse/overuse). +[Skip to recommendations](#recommendations) + ## Research Prior to PyPI XMLRPC search being disabled, we: diff --git a/docs/html/ux-research-design/research-results/pip-upgrade-conflict.md b/docs/html/ux-research-design/research-results/pip-upgrade-conflict.md index c0ea2098068..6c585ac3310 100644 --- a/docs/html/ux-research-design/research-results/pip-upgrade-conflict.md +++ b/docs/html/ux-research-design/research-results/pip-upgrade-conflict.md @@ -4,6 +4,8 @@ Currently, pip does _not_ take into account packages that are already installed when a user asks pip to upgrade a package. This can cause dependency conflicts for pip's users. +[Skip to recommendations](#recommendations) + ## Research We published a [survey](https://bit.ly/2ZqJijr) asking users how they would solve the following scenario: diff --git a/docs/html/ux-research-design/research-results/prioritizing-features.md b/docs/html/ux-research-design/research-results/prioritizing-features.md index dcff8cb1c57..47c75053369 100644 --- a/docs/html/ux-research-design/research-results/prioritizing-features.md +++ b/docs/html/ux-research-design/research-results/prioritizing-features.md @@ -1,10 +1,12 @@ -# Prioritizing features +# Prioritizing pip features ## Problem The pip development team is small, and has limited time and energy to work on issues reported via the [issue tracker](https://github.com/pypa/pip/issues). There is also a significant backlog of issues (782 as of November, 2020) for the team to respond to. For the team to prioritize their work based on what will have the most impact, we need to develop a better understanding of what users want from pip. +[Skip to recommendations](#recommendations) + ## Research To help answer this question, we developed a "buy a feature" survey, with the following scenario: diff --git a/docs/html/ux-research-design/research-results/users-and-security.md b/docs/html/ux-research-design/research-results/users-and-security.md index 543217b1bf7..7502b1e785e 100644 --- a/docs/html/ux-research-design/research-results/users-and-security.md +++ b/docs/html/ux-research-design/research-results/users-and-security.md @@ -16,8 +16,6 @@ We asked participants to tell us how often they: 2. Think about the security and integrity of the (Python) software they install (with pip) 3. Think about the security and integrity of the (Python) code they create -[Skip to recommendations](#recommendations) - ## Results While the security and integrity of the software users install (51%) and make (71%) is important to research participants, less than 7% do code audits of the packages or code they install with pip.