diff options
| author | Nicole Harris <n.harris@kabucreative.com> | 2021-07-28 22:32:20 +0100 |
|---|---|---|
| committer | Nicole Harris <n.harris@kabucreative.com> | 2021-07-28 22:32:20 +0100 |
| commit | 3382d3a6c3a3fbafc221f5358bf39f40f6652bda (patch) | |
| tree | 9c7b6d3481e038add49b6c6da9af4f8a2fa8bce6 | |
| parent | dcffff7a8db66e5532290ba884c3c4a6494d141d (diff) | |
| download | pip-3382d3a6c3a3fbafc221f5358bf39f40f6652bda.tar.gz | |
Clean up content
7 files changed, 233 insertions, 607 deletions
diff --git a/docs/html/ux-research-design/2020-research-outputs/about-our-users.md b/docs/html/ux-research-design/2020-research-outputs/about-our-users.md index eae507e88..a1d72d1f7 100644 --- a/docs/html/ux-research-design/2020-research-outputs/about-our-users.md +++ b/docs/html/ux-research-design/2020-research-outputs/about-our-users.md @@ -1,676 +1,291 @@ -# About pip's users +# About pip's Users ## Research -It is important to understand users' background, their cultural environment, and how they experience the world. To get this understanding we asked our participants about: their location in the world, their spoken language, if they identified as members of an underrepresented group in the Python community, and also to understand their disabilities and if they affected their usage of pip. +It is important to understand users' background, their cultural environment, and how they experience the world. -## Summary - -164 participants took part in our "Who uses pip?” user research, 40% of these came from English speaking countries. 80% of participants came from Europe/North America. - -Approx. 60% of participants did not identify as members of under-represented communities. The majority of those who did identify as under-represented did so for gender reasons. - -The majority of participants (94%) responded that they did not have a disability. Those that did have a disability, the majority were cognitive disabilities (Attention Deficit Hyperactivity Disorder (ADHD), Autism, Aspergers, Dyslexia) or a hearing disability. - -## Recommendations - -### Supporting languages other than English - -The ideal situation to support non-English speaking pip users would be to translate documentation into their language, some alternatives could be drawn from the Python community: - -#### Identify community members who could act as other language documentation stewards +To develop this understanding about pip's users, we published a “Who uses pip?” survey that asked users about : -The Python community is global, and so has members who speak many languages. By identifying members who could take care of translating, or identifying already created documentation, this would help non-English speaking pip users. +* Their location in the world +* Their spoken language +* If they identified as members of an underrepresented group in the Python community +* Their disabilities and if those disabilities affected their usage of pip -#### Identify pip documentation in other languages and link to it from the official pip documentation +[Skip to recommendations](#recommendations) -Our research has already found that users use a mixture of pip documentation, search engine searches, Stack Overflow and blogs/websites to find good documentation. - -Providing a list of documentation in different languages for pip users would make it easier to find that documentation. - -### Supporting pip users with disabilities - -Pip's operation is actually very good for users with disabilities. Being a terminal application the user has a large amount of control on how they experience pip - customisation of interface visual preferences (to use contrasting colours, font size and type), there are no distracting images or ancillary content, they can use visual and auditory alerts. - -#### Improving pip output - -However the main improvement that should be made is to improve pips output. +## Summary -Right now pip's output is too verbose - it generates an unhelpful amount of output during it's operation. This causes usability issues for all users - especially users with cognitive disabilities. +164 people responded to the survey, with 40% of these coming from English speaking countries. 80% of participants came from Europe or North America. -Pip's output should be improved by: +Approx. 60% did not identify as members of an underrepresented group. The majority of participants who did identify as underrepresented did so for gender reasons. -- Distinguishing what is important
information at the moment (e.g. at install of a package) and remove unimportant information from the terminal output. The information can still be logged to the log files if needed. -- Reduce the number of verbosity levels to 3. Right now there are 7 <?> levels of verbosity. - - Verbosity 0 - shows only what packages are to be installed, notifications identified as important about the operation, any errors and the final outcome - - Verbosity 1 - shows more detail about the packages being installed - - Verbosity 2 - shows full information which is also logged to logfiles +The majority of participants (94%) responded that they did not have a disability. Of those that did have a disability, the majority were cognitive disabilities (Attention Deficit Hyperactivity Disorder (ADHD), Autism, Aspergers, Dyslexia) or a hearing disability. -## Participant demographics +## Participant Demographics ### Location -The majority of participation came from North American, Western European countries. Participation from African, Asian, and Middle-Eastern countries was low. - - -Fig. 1: Global distribution of pip research participants. - -<table> - <tr> - <td><em>Country Name</em> - </td> - <td>Number of participants - </td> - </tr> - <tr> - <td>United States of America - </td> - <td><p style="text-align: right"> -42</p> - - </td> - </tr> - <tr> - <td>United Kingdom - </td> - <td><p style="text-align: right"> -17</p> - - </td> - </tr> - <tr> - <td>France - </td> - <td><p style="text-align: right"> -12</p> - - </td> - </tr> - <tr> - <td>Germany - </td> - <td><p style="text-align: right"> -11</p> - - </td> - </tr> - <tr> - <td>Canada - </td> - <td><p style="text-align: right"> -10</p> - - </td> - </tr> - <tr> - <td>Netherlands - </td> - <td><p style="text-align: right"> -8</p> - - </td> - </tr> - <tr> - <td>Spain - </td> - <td><p style="text-align: right"> -6</p> - - </td> - </tr> - <tr> - <td>Switzerland - </td> - <td><p style="text-align: right"> -5</p> - - </td> - </tr> - <tr> - <td>Nigeria - </td> - <td><p style="text-align: right"> -4</p> - - </td> - </tr> - <tr> - <td>India - </td> - <td><p style="text-align: right"> -4</p> - - </td> - </tr> - <tr> - <td>Czech Republic - </td> - <td><p style="text-align: right"> -4</p> - - </td> - </tr> - <tr> - <td>Argentina - </td> - <td><p style="text-align: right"> -4</p> - - </td> - </tr> - <tr> - <td>Sweden - </td> - <td><p style="text-align: right"> -3</p> - - </td> - </tr> - <tr> - <td>Australia - </td> - <td><p style="text-align: right"> -3</p> - - </td> - </tr> - <tr> - <td>Ukraine - </td> - <td><p style="text-align: right"> -2</p> - - </td> - </tr> - <tr> - <td>Taiwan - </td> - <td><p style="text-align: right"> -2</p> - - </td> - </tr> - <tr> - <td>Russia - </td> - <td><p style="text-align: right"> -2</p> - - </td> - </tr> - <tr> - <td>Greece - </td> - <td><p style="text-align: right"> -2</p> - - </td> - </tr> - <tr> - <td>Colombia - </td> - <td><p style="text-align: right"> -2</p> - - </td> - </tr> - <tr> - <td>Chile - </td> - <td><p style="text-align: right"> -2</p> - - </td> - </tr> - <tr> - <td>Brazil - </td> - <td><p style="text-align: right"> -2</p> - - </td> - </tr> - <tr> - <td>Belgium - </td> - <td><p style="text-align: right"> -2</p> - - </td> - </tr> - <tr> - <td>Uganda - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Turkey - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Singapore - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Serbia - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Norway - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Luxembourg - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Japan - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Italy - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Israel - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Ireland - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Hungary - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Ghana - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Finland - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Bulgaria - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td>Austria - </td> - <td><p style="text-align: right"> -1</p> - - </td> - </tr> - <tr> - <td><strong>Total</strong> - </td> - <td><p style="text-align: right"> -<strong>164</strong></p> - - </td> - </tr> -</table> - - - -## Participant's first language +The majority of participants came from North America and Western Europe. Participation from pip users in Africa, Asia, and the Middle-East was low. + + + +Fig. X: Global distribution of pip research participants. + +|Country Name|Number of participants| +|--- |--- | +|United States of America|42| +|United Kingdom|17| +|France|12| +|Germany|11| +|Canada|10| +|Netherlands|8| +|Spain|6| +|Switzerland|5| +|Nigeria|4| +|India|4| +|Czech Republic|4| +|Argentina|4| +|Sweden|3| +|Australia|3| +|Ukraine|2| +|Taiwan|2| +|Russia|2| +|Greece|2| +|Colombia|2| +|Chile|2| +|Brazil|2| +|Belgium|2| +|Uganda|1| +|Turkey|1| +|Singapore|1| +|Serbia|1| +|Norway|1| +|Luxembourg|1| +|Japan|1| +|Italy|1| +|Israel|1| +|Ireland|1| +|Hungary|1| +|Ghana|1| +|Finland|1| +|Bulgaria|1| +|Austria|1| +|Total|164| + +## Participant's First Language Even though the research was carried out mainly in English, 51% of participants spoke languages other than English. - - -<p id="gdcalert2" ><span style="color: red; font-weight: bold">>>>>> gd2md-html alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert3">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>>> </span></p> - - - -NB: English includes British English and American English. Some participants gave more than 1 answer, their first answer is included here. - - -## Are you a member of an underrepresented minority in the Python users community? - -We asked research participants if they identified as members of an underrepresented minority. We gave participants a broad definition of underrepresented - gender, age, educational background, language you speak, what you use Python for. The objective of this question was to discover participants' opinions of their understanding of underrepresented. - -(This question was included _after _the survey was published. Total participants was 106, as opposed to all other questions which had 164) - - +|What spoken language do you feel is your first?|Number of participants| +|--- |--- | +|English|79| +|French|18| +|Spanish|12| +|German|11| +|Russian|5| +|Czech|4| +|Italian|4| +|Portuguese|3| +|Dutch|3| +|Ukrainian|2| +|Swedish|2| +|Greek|2| +|Catalan|2| +|Mandarin|2| +|Hungarian|2| +|Bengali|1| +|Luxembourgish|1| +|Bulgarian|1| +|Romanian|1| +|Chinese|1| +|Norwegian|1| +|Serbian|1| +|Polish|1| +|Hebrew|1| +|Indonesian|1| +|Malayalam|1| + +NB: English includes British English and American English. Some participants gave more than one answer, their first answer is included here. + +## Participants who identified as underrepresented in the Python community + +We asked research participants if they identified as members of an underrepresented group within the Python community. + +The wording of this question was deliberately broad to discover participants' understanding of the term “underrepresented” - we listed gender, age, educational background, spoken language, and what they use Python for as a non-exhaustive list of examples. + + Of the 23.5% that responded "Yes" the answers were classified as follows : -<table> - <tr> - <td><strong>Underrepresentation category</strong> - </td> - <td><strong>Count</strong> - </td> - </tr> - <tr> - <td>Gender - </td> - <td><p style="text-align: right"> -9</p> - - </td> - </tr> - <tr> - <td>Cultural - </td> - <td><p style="text-align: right"> -3</p> - - </td> - </tr> - <tr> - <td>Age - </td> - <td><p style="text-align: right"> -3</p> - - </td> - </tr> - <tr> - <td>Immigration status - </td> - <td><p style="text-align: right"> -2</p> - - </td> - </tr> - <tr> - <td>Neurodiversity - </td> - <td><p style="text-align: right"> -3</p> - - </td> - </tr> - <tr> - <td>Other - </td> - <td><p style="text-align: right"> -6</p> - - </td> - </tr> - <tr> - <td>No answer - </td> - <td><p style="text-align: right"> -8</p> - - </td> - </tr> -</table> - - - -### What do these results mean? - -The majority of participants did not identify as part of an underrepresented community. Due to the small sample size these results cannot be seen as representative of the whole pip user base. +|Underrepresentation category|Count| +|--- |--- | +|Gender|9| +|Cultural|3| +|Age|3| +|Immigration status|2| +|Neurodiversity|3| +|Other|6| +|No answer|8| +NB: This question was included after the survey was published. Total participants was 106, as opposed to all other questions which had 164. -#### Participant comments about identifying/not identifying as under-represented - -Here is a sample of noteworthy comments from these different groups. - - -##### Related to gender - -_(I am) LGBTQ/IA+ - _Participant 242608909 +### Interpreting these Results -_I am a 25 year old female Colombian developer. - _Participant 242611698 +The majority of participants did not identify as part of an underrepresented group. However, due to the small sample size these results cannot be seen as representative of the whole pip user base. -_Female, 39, no computer science background whatsoever, self taught. - _Participant 242614039 - - -##### Related to culture +#### Participant comments about identifying/not identifying as under-represented -_The hispanic community is quite underrepresented in the web in general - Participant 242599212_ +Here is a sample of noteworthy comments from these different groups: -_I am a 1st generation Dominican-American. My parents are from the Dominican Republic. - _Participant 242769361 +##### Related to Gender +> "(I am) LGBTQ/IA+" - Participant 242608909 +> "I am a 25 year old female Colombian developer." - Participant 242611698 +> "Female, 39, no computer science background whatsoever, self taught." - Participant 242614039 -##### Age related +##### Related to Culture -_Older age, I am 50 now. - _Participant 242769743 +> "The hispanic community is quite underrepresented in the web in general" - Participant 242599212 +> "I am a 1st generation Dominican-American. My parents are from the Dominican Republic." - Participant 242769361 +##### Related to Age -##### Neurodiversity related +> "Older age, I am 50 now." - Participant 242769743 -_I'm a woman. And autistic. But the latter might not be underrepresented ;) - _Participant 243428773 +##### Related to Neurodiversity +> "I'm a woman. And autistic. But the latter might not be underrepresented ;)" - Participant 243428773 ##### Other -_Veterans who entered tech post-military _- Participant 243524784 - -_I'm not sure it applies, but I do feel that distributing CLI packages to workstations is painful with pip. I'm sure in server side environments where you have control over the host it's much easier. - _Participant 242943955 +> "Veterans who entered tech post-military" - Participant 243524784 -Noteworthy answers where the participant did not identify as under-represented (or were not sure) - +Noteworthy answers where the participant did not identify as under-represented (or were not sure): -_I'm a young white cis male, so by far not a minority in those aspects. But at the same time I'm from a third world country, Argentina, and that sometimes (and I emphasize, only sometimes) makes me feel like a minority. When participating in our local communities (Python Argentina), I feel clearly not-minority, and with the responsibility of helping minorities, trying to build a more welcoming and fair environment for them. But when I participate in the broader global community, at times I feel underrepresented, seeing it mostly guided by english-seaking people from first world countries. But if I have to choose, I would say I mostly feel not-minority, because I mostly interact with people from our local communities, where I'm not part of a minority. - _Participant 242592869 +> "I'm a young white cis male, so by far not a minority in those aspects. But at the same time I'm from a third world country, Argentina, and that sometimes (and I emphasize, only sometimes) makes me feel like a minority. When participating in our local communities (Python Argentina), I feel clearly not-minority, and with the responsibility of helping minorities, trying to build a more welcoming and fair environment for them. But when I participate in the broader global community, at times I feel underrepresented, seeing it mostly guided by english-s[p]eaking people from first world countries. But if I have to choose, I would say I mostly feel not-minority, because I mostly interact with people from our local communities, where I'm not part of a minority." - Participant 242592869 -_As a CIS male I conform the majoritarian group in the IT world. I'm hopeful that things are changing everywhere, and will keep changing: inclusion is getting bigger and better, more and more people are starting their careers as devs or similar, disregarding ethnicity and/or sexual orientation and that's great! And we need to keep fighting for that. - _Participant 243455292 +> "As a CIS male I conform the majoritarian group in the IT world. I'm hopeful that things are changing everywhere, and will keep changing: inclusion is getting bigger and better, more and more people are starting their careers as devs or similar, disregarding ethnicity and/or sexual orientation and that's great! And we need to keep fighting for that." - Participant 243455292 - -## Participant disabilities +## Participant Disabilities Disabilities - physical, motor, cognitive, hearing, speech - alter how people perceive and interact with the world around them - software included. We asked participants about their disabilities and how it affected their usage of pip. -Understanding these disabilities are important particularly when designing pip command structures, and designing pip output. - -The majority of participants (150) responded that they did not have a disability. Those that did have a disability, the majority were cognitive disabilities (Attention Deficit Hyperactivity Disorder (ADHD), Autism, Aspergers, Dyslexia) or a hearing disability. +Understanding these disabilities is important particularly when designing pip command structures, and designing pip output. +The majority of participants (91%) responded that they did not have a disability. Of those that told us that have a disability, the majority were cognitive disabilities (Attention Deficit Hyperactivity Disorder (ADHD), Autism, Aspergers, Dyslexia, or a hearing disability. ### How many participants identified as having a disability? +|Do you self-identify as someone who has a disability?|Number of responses| +|No|150| +|Yes|14| +|Grand Total|164| -<table> - <tr> - <td><em>Answer to the question: Do you self-identify as someone who has a disability?</em> - </td> - <td>Number of responses - </td> - </tr> - <tr> - <td>No - </td> - <td>150 - </td> - </tr> - <tr> - <td>Yes - </td> - <td>14 - </td> - </tr> - <tr> - <td><strong>Grand Total</strong> - </td> - <td><strong>164</strong> - </td> - </tr> -</table> - - - - -<p id="gdcalert4" ><span style="color: red; font-weight: bold">>>>>> gd2md-html alert: inline image link here (to images/image4.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert5">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>>> </span></p> - - - - - - -### Types of disabilities participants mentioned - +### Types of disabilities mentioned by participants #### Vision -Participants' who answered yes to this question were partially sighted. Their vision disability was not corrected by glasses however it did not significantly affect their usage of pip. - +Participants who answered yes to this question were partially sighted. Their vision disability was not corrected by glasses, but did not significantly affect their usage of pip. #### Hearing -5 participants identified as having a hearing impairment, or hearing loss. While this disability made participants lives more difficult, it did not affect their usage of pip: +Five participants identified as having a hearing impairment, or hearing loss. While this disability made participants lives more difficult, it did not affect their usage of pip: -_Being hard of hearing/impaired makes my life much harder, but so far it never has impacted my usage of pip. Perhaps because I haven‘t used parts of it that would? _- 242934019 +> "Being hard of hearing/impaired makes my life much harder, but so far it never has impacted my usage of pip. Perhaps because I haven‘t used parts of it that would?" - Participant 242934019 -_Not at all given that everything happens by text in my console._ - Participant 243455292 +> "Not at all given that everything happens by text in my console." - Participant 243455292 -However it does affect the way they consume pip learning materials: if video is being used for learning or support, they should have captions/subtitles/transcriptions available. +However it did affect the way they consume pip learning materials: if video is being used for learning or support, they should have captions/subtitles/transcriptions available. -_[...] any videos released, it is so helpful if there is either a) transcripts, or b) captions. \ -_- Participant 243524784 +> "any videos released, it is so helpful if there is either a) transcripts, or b) captions." - Participant 243524784 -#### Cognitive disabilities +#### Cognitive Disabilities -9 participants expressed cognitive disabilities including undefined mental health conditions, Attention Deficit Hyperactivity Disorder (ADHD), Autism, Aspergers, Dyslexia. +Nine participants expressed cognitive disabilities including undefined mental health conditions, Attention Deficit Hyperactivity Disorder (ADHD), Autism, Aspergers, Dyslexia. These participants did not explain how their cognitive disabilities affect their usage of pip, however there are guidelines and best practices for designing for people with cognitive disabilities. -#### Physical or mobility disability - -1 participant responded that they had a physical or mobility disability, but did not give detail about it in relation to their usage of pip. - - -## Use of assistive technology - -Assistive technology is - -The majority of participants (94%) never used assistive technology equipment. +#### Physical or Mobility Disability +One participant responded that they had a physical or mobility disability, but did not give detail about it in relation to their usage of pip. +## Participants use of Assistive Technology -<p id="gdcalert5" ><span style="color: red; font-weight: bold">>>>>> gd2md-html alert: inline image link here (to images/image5.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert6">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>>> </span></p> +The term “assistive technology” (AT) is used to describe products or systems that support and assist individuals with disabilities, restricted mobility or other impairments to perform functions that might otherwise be difficult or impossible. A subset of these are used to make computer technology - hardware and software - more accessible. Common examples of AT used with computer technology are: screen readers, text-to-speech outputs/inputs. +The majority of participants (94%) said that they have never used assistive technology. - +|Do you use assistive technology (AT) when using computers?|Number of responses| +|No, I have never used it|128| +|I only use it when needed|3| +|I use it everyday|1| +|I have used it in the past, but not anymore|4| +Of the eight participants who have used assistive technology, one participant uses assistive technology every day with: -One participant (242933506) uses the following every day: +* Text-to-speech output as “text to speech allow(s) me to listen and learn when my eyes get strained.” +* Speech-to-text input as they like using their “tablet and makes typing easier” +* On-screen keyboards +* Input switches/touch screens -- Text-to-speech output as "text to speech it allow me to listen and learn when my eyes get strained.” -- Speech-to-text input as they like using their "tablet and makes typing easier” -- On-screen keyboards -- Input switches/touch screens +A further seven participants use assistive technology only as needed: +> "I use custom display filter software to do things like colorize key lines of output automatically (to draw my eye/attention), and provide digit dilimination (I.E. help me tell 1000 and 10000 apart) when using a text console application." -### I use it only when needed +> "The standard Mac user interface design contains enough assistive technology without my needing to use any features which are specifically intended solely as assistive functions." -7 participants use AT only as needed. +> "I sometimes use it to make sure that my code will work correctly with AT." -I use custom display filter software to do things like colorize key lines of output automatically (to draw my eye/attention), and provide digit dilimination (I.E. help me tell 1000 and 10000 apart) when using a text console application. +### Operating systems used with assistive technology -The standard Mac user interface design contains enough assistive technology without my needing to use any features which are specifically intended solely as assistive functions. +Participants use assistive technology across the three most popular desktop operating systems - Linux (most popular), Windows (2nd most popular), and Windows. -I sometimes use it to make sure that my code will work correctly with AT. + +### Assistive technology when using pip -### How well do your Assistive Technologies work when you use pip? - -For all participants who used AT, it worked very well for them, they did not report problems. - -When using pip help pipe to unless more/less is used, output can scroll off top of the current terminal window - screen readers do not cope well in this case. The same can happen for installs and failed builds cause a lot of output, often with the critical part off the top of the screen. - - -### What operating system(s) are used with Assistive Technology? - -Participants have used AT across 3 most popular desktop operating systems - Linux (most popular), Windows (2nd most popular), and Linux. - - - -<p id="gdcalert6" ><span style="color: red; font-weight: bold">>>>>> gd2md-html alert: inline image link here (to images/image6.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert7">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>>> </span></p> - - - - - - -### In your view, what is the most important accessibility improvement we should make to pip? +We asked participants how well their assistive technologies worked when they use pip. All participants using assistive technology with pip said it worked well for them. +We received some feedback about screen readers not coping well with long output, with users experiencing difficulties accessing content at the top of the current terminal window. Therefore, commands or actions (e.g. pip help, pip install, failed builds) that generate a lot of content can be a problem for screenreader users. +## Recommendations -**AT setups** +### Supporting languages other than English -Programmable ergonomic keyboard and a large easy-to-manipulate trackball (which pip doesn't need, being a CLI tool) +As 51% of participants speak a language other than English, we recommend that the pip team add localization support to the pip documentation and reach out to the community to find pip users who might be willing to contribute translations. Translators that have [contributed translations to PyPI](https://hosted.weblate.org/projects/pypa/warehouse/) may be a good starting point. -Software is a set of custom scripts I've written. +If this is not possible, we recommend linking to useful resources in languages other than English from the pip documentation, as we know from our other research that users use a mixture of the official documentation, search engine searches, Stack Overflow and blogs/websites to find solutions to their problems. -I have my custom keyboard between me and my screen, just like any typical user. +### Supporting pip users with disabilities +Pip's operation is generally very good for users with disabilities. Being a command line application there are no distracting images or ancillary content, and the user has a large amount of control on how they experience pip via customisation of interface visual preferences (to use contrasting colours, font size and type) and visual and auditory alerts. -## Designing for people with disabilities resources +To better support pip's users with disabilities, the pip team should: -[An Introduction to inclusive design](https://www.nomensa.com/blog/2011/introduction-inclusive-design) +* Ensure any future video or audio support materials are provided with captions +* Improve pip's output (see below) -[How ADHD and dyslexia teach you to do better UX design](https://themasters.io/blog/posts/how-adhd-dyslexia-teach-better-ux-design) +#### Improving pip output -[Improve User Experience by Designing with Cognitive Differences in Mind](https://noti.st/elizabethschafer/fg3BR4) +Pip's output is currently too verbose, generating an unhelpful amount of output during its operation. This causes usability issues for all users - especially users with cognitive disabilities. -[Designing accessible software - guidelines for different disabilities](https://ukhomeoffice.github.io/accessibility-posters/) +Pip's output should be improved by: -[Designing
for Children
with ADHD: The Search for Guidelines for Non-Experts](https://uxpamagazine.org/designing_children_adhd/) (written for children however applicable generally) +* Retaining only the information that is important to users in their current moment (e.g. at install of a package) +* Removing unimportant information from the terminal output. The information can still be logged to the log files if needed. +* Reducing the number of verbosity levels to three. Right now there are seven levels of verbosity, which is overwhelming and in no way useful. We recommend: + * Verbosity 0 - shows only what packages are to be installed, notifications identified as important about the operation, any errors and the final outcome + * Verbosity 1 - shows more detail about the packages being installed + * Verbosity 2 - shows full information which is also logged to logfiles -[Designing for dyslexia](https://uxplanet.org/designing-for-dyslexia-6d12e8c41cd7) +## Further reading -## Participant introduction to Python +### Designing for people with disabilities -The majority of participants were introduced to Python in school - second-level school, university, or postgraduate education. +* [An Introduction to inclusive design](https://www.nomensa.com/blog/2011/introduction-inclusive-design) +* [How ADHD and dyslexia teach you to do better UX design](https://themasters.io/blog/posts/how-adhd-dyslexia-teach-better-ux-design) +* [Improve User Experience by Designing with Cognitive Differences in Mind](https://noti.st/elizabethschafer/fg3BR4) +* [Designing accessible software - guidelines for different disabilities](https://ukhomeoffice.github.io/accessibility-posters/) +* [Designing
for Children
with ADHD: The Search for Guidelines for Non-Experts](https://uxpamagazine.org/designing_children_adhd/) (written for children however applicable generally) +* [Designing for dyslexia](https://uxplanet.org/designing-for-dyslexia-6d12e8c41cd7) diff --git a/docs/html/ux-research-design/2020-research-outputs/improving-pips-documentation.md b/docs/html/ux-research-design/2020-research-outputs/improving-pips-documentation.md index 88a0276f3..da0af9b2d 100644 --- a/docs/html/ux-research-design/2020-research-outputs/improving-pips-documentation.md +++ b/docs/html/ux-research-design/2020-research-outputs/improving-pips-documentation.md @@ -4,6 +4,8 @@ We want to establish whether or not the [official pip documentation](https://pip.pypa.io/en/stable/) helps users to solve their pip problems. We also want to identify possible improvements to the content and structure of the docs. +[Skip to recommendations](#recommendations) + ## Research ### Interviews @@ -40,7 +42,7 @@ Unfortunatly, we did not gather any useful feedback via this effort ## Response / results In total, we: -- Conducted 5 user interviews about pip's documentatation +- 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 @@ -48,12 +50,12 @@ In general, we found that pip's documentation is underutilized by the community, In response to the question "When you have a problem using pip, what do you do?" (multiselect): -- 81.9% of respondends Google it -- 56.9% of respondends search or ask on Stack Overflow -- 33.8% of respondends use pip help from the command line -- **25.6% of respondends go to the pip docs** -- 20.6% of respondends go the the Python Packaging User Guide -- 8.1% of respondends ask on a forum, community board, or chat channel +- 81.9% of respondents Google it +- 56.9% of respondents search or ask on Stack Overflow +- 33.8% of respondents use pip help from the command line +- **25.6% of respondents go to the pip docs** +- 20.6% of respondents go the the Python Packaging User Guide +- 8.1% of respondents ask on a forum, community board, or chat channel  @@ -68,10 +70,10 @@ 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 -- The documentaiton information architecture is difficult to navigate (the monolithic structure of the user guide is a problem) and does not prioritise the most useful content +- The documentation information architecture is difficult to navigate (the monolithic structure of the user guide is a problem) and does not prioritise the most useful content - There should be more instructions specific to each user's different situation (e.g. what operating system they are using) - The scope of the documentation is unclear -- The documentaton should recognise that pip exists within an ecosystem of other packaging tools +- The documentation should recognise that pip exists within an ecosystem of other packaging tools - ["There should be one-- and preferably only one --obvious way to do it."](https://www.python.org/dev/peps/pep-0020/) - i.e. the documentation should provide stronger recommendations While some users mentioned that video would be helpful, more said that video was too long, or inappropriate for the kind of problems they experience using pip. @@ -178,7 +180,7 @@ From our keyword research we identified seven _query types_: "about pip", "insta </details> <br/> -The prevelance of "install pip" queries strongly suggests that the current installation documentation should be improved and that users are searching for solutions specific to their operating system. +The prevalence of "install pip" queries strongly suggests that the current installation documentation should be improved and that users are searching for solutions specific to their operating system. The "about pip" queries also suggest that beginners would benefit from documentation that better explains pip basics - e.g. what pip is and what it does. @@ -187,14 +189,14 @@ The "about pip" queries also suggest that beginners would benefit from documenta Based on our research, we recommend that the pip team: - Revise the structure of the documentation: - - Break monolithic pages into standlone 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 troublehsoot their pip problems. + - 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 - 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 -- Develop a beginner's guide that walks new pip users through everything they need to know to use pip's most basic functonality. 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 +- 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. @@ -207,7 +209,7 @@ Based on our research, we recommend that the pip team: ### Suggested site map -Based on the above user iput, 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. +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.  @@ -220,7 +222,7 @@ Based on the above user iput, we have developed a proposed [site map](https://i. - To link to other (more detailed) areas of the documentation *Suggested content:* -- Quick installation guide, including how to use a virtual environment. This is neccessary for user who want to install more than one Python project on their machine. +- 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) --- @@ -257,7 +259,7 @@ Based on the above user iput, we have developed a proposed [site map](https://i. *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? -- Breifly introduce other packaging projects. Link to https://packaging.python.org/key_projects/ +- Briefly introduce other packaging projects. Link to https://packaging.python.org/key_projects/ --- #### Node 3.0: Installing pip @@ -265,7 +267,7 @@ Based on the above user iput, we have developed a proposed [site map](https://i. - To help pip users install pip *Suggested content:* -- Refactor current page, ephasising pathways for different operating systems +- 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 --- @@ -292,7 +294,7 @@ Step by step tutorial (possibly broken into several pages) that covers: #### Node 4.2: Advanced tutorial - using pip behind a proxy *Page purpose:* -- To help advanced pip users acheive specific goals +- To help advanced pip users achieve specific goals *Suggested content:* - Step by step tutorial for using pip behind a proxy @@ -317,7 +319,7 @@ Break down current user guide into separate pages, or pages linked by subject. S - Running pip - Installing Packages - Uninstalling Packages -- Environment recreatiion with requirements files +- Environment recreation with requirements files - sub heading: "pinned version numbers" - sub heading: "hash checking mode" - Listing Packages diff --git a/docs/html/ux-research-design/2020-research-outputs/override-conflicting-dependencies.md b/docs/html/ux-research-design/2020-research-outputs/override-conflicting-dependencies.md index fd93813a0..7c20e338b 100644 --- a/docs/html/ux-research-design/2020-research-outputs/override-conflicting-dependencies.md +++ b/docs/html/ux-research-design/2020-research-outputs/override-conflicting-dependencies.md @@ -10,6 +10,7 @@ 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 diff --git a/docs/html/ux-research-design/2020-research-outputs/pip-force-reinstall.md b/docs/html/ux-research-design/2020-research-outputs/pip-force-reinstall.md index a9499cd59..5d06e2658 100644 --- a/docs/html/ux-research-design/2020-research-outputs/pip-force-reinstall.md +++ b/docs/html/ux-research-design/2020-research-outputs/pip-force-reinstall.md @@ -10,6 +10,8 @@ We want to find out if users understand (or desire) this implicit behaviour. More information can be found on [this GitHub issue](https://github.com/pypa/pip/issues/8238). +[Skip to recommendations](#recommendations) + ## Research To help us understand what users want from the `--force-reinstall` option, we launched a survey with the following scenario: @@ -53,10 +55,10 @@ In total we received 190 responses to our survey, with 186 people telling us wha - **15.6%** (29/186) of respondents said that pip should reinstall requests and its dependencies, updating all these packages to the latest compatible versions - **14%** (26/186) of respondents said that pip should reinstall the same version of requests, and not reinstall request's dependencies -If we group responses into "uprade" or "do not upgrade" (ignoring responses that could not be grouped), we find: +If we group responses into "upgrade" or "do not upgrade" (ignoring responses that could not be grouped), we find: - 46.32% (88/186) of respondents thought that pip should install the same version of requests - i.e. that `--force-reinstall` should *not* implicitly upgrade -- 43.16% (82/186) of respondents thought that pip should upgrade requests to the lastest version - i.e that `--force-reinstall` *should* implicitly upgrade +- 43.16% (82/186) of respondents thought that pip should upgrade requests to the latest version - i.e that `--force-reinstall` *should* implicitly upgrade Most respondents use `--force-reinstall` "almost never" (65.6%): @@ -65,7 +67,7 @@ Most respondents use `--force-reinstall` "almost never" (65.6%): Amongst respondents who said they use `--force-resinstall` often or very often: - 54.54% (6/11) of respondents thought that pip should install the same version of requests - i.e. that `--force-reinstall` should *not* implicitly upgrade -- 45.45% (5/11) of respondents thought that pip should upgrade requests to the lastest version - i.e that `--force-reinstall` *should* implicitly upgrade +- 45.45% (5/11) of respondents thought that pip should upgrade requests to the latest version - i.e that `--force-reinstall` *should* implicitly upgrade Respondents find `--force-reinstall` less useful than useful: @@ -75,7 +77,7 @@ Respondents find `--force-reinstall` less useful than useful: Amongst respondents who said they find `--force-resinstall` useful or very useful: - 38.46% (20/52) of respondents thought that pip should install the same version of requests - i.e. that `--force-reinstall` should *not* implicitly upgrade -- 50% (26/52) of respondents thought that pip should upgrade requests to the lastest version - i.e that `--force-reinstall` *should* implicitly upgrade +- 50% (26/52) of respondents thought that pip should upgrade requests to the latest version - i.e that `--force-reinstall` *should* implicitly upgrade ## Recommendations diff --git a/docs/html/ux-research-design/2020-research-outputs/pip-search.md b/docs/html/ux-research-design/2020-research-outputs/pip-search.md index 033cf2bf8..752e6259e 100644 --- a/docs/html/ux-research-design/2020-research-outputs/pip-search.md +++ b/docs/html/ux-research-design/2020-research-outputs/pip-search.md @@ -1,9 +1,11 @@ -# Pip search +# pip search ## Problem 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: @@ -26,9 +28,9 @@ However, search ranked lower than the following features: 2. Show information about all installed packages *707* 3. Show information about a single installed package *596* -We received 302 respones to the pip search survey, with 62 of the 302 (20.5%) respondends either not knowing that the command existed, never using it, or using it "rarely". +We received 302 responses to the pip search survey, with 62 of the 302 (20.5%) respondents either not knowing that the command existed, never using it, or using it "rarely". -We found that the remaining ~80% of respondends who do use pip search use it to: +We found that the remaining ~80% of respondents who do use pip search use it to: - Find/search for the right/new/alternate packages to install: - Checking package name (verify correct spelling) @@ -41,7 +43,7 @@ In general, pip search is regarded as: - more useful than not useful - more clear than not clear -When asked if pip should search on items _other_ than the package name, respondends most commonly asked to search the package description: +When asked if pip should search on items _other_ than the package name, respondents most commonly asked to search the package description:  diff --git a/docs/html/ux-research-design/2020-research-outputs/pip-upgrade-conflict.md b/docs/html/ux-research-design/2020-research-outputs/pip-upgrade-conflict.md index a564f96e0..1edcdb9f7 100644 --- a/docs/html/ux-research-design/2020-research-outputs/pip-upgrade-conflict.md +++ b/docs/html/ux-research-design/2020-research-outputs/pip-upgrade-conflict.md @@ -1,8 +1,10 @@ -# Pip upgrade conflict +# pip upgrade conflict ## Problem 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/2020-research-outputs/prioritizing-features.md b/docs/html/ux-research-design/2020-research-outputs/prioritizing-features.md index 64224875d..721bea998 100644 --- a/docs/html/ux-research-design/2020-research-outputs/prioritizing-features.md +++ b/docs/html/ux-research-design/2020-research-outputs/prioritizing-features.md @@ -4,6 +4,8 @@ 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: |