Blog by Sumana Harihareswara, Changeset founder

24 Apr 2024, 11:42 a.m.

Model UX Research & Design Docs for Command-Line Open Source

If you work on open source software, especially command-line tools, I want you to know about newly available research reports and design guidance, and a user research HOWTO, that you can pick up and reuse.

The pip work and how you can learn from it

Back in 2020, during grant-funded work on the next-generation pip resolver, the consultancy Superbloom (previously Simply Secure) did fascinating user experience research and design work. I was the project manager on this work, and can attest that working with UX experts on pip was crucial and valuable. The more we knew about users’ experience, the better decisions we could make.

During that work, they wrote several useful documents that took a while to get merged, but now live in pip’s documentation! Like:

Even if your work has nothing to do with pip, consider skimming those. The most exciting thing about them isn't their literal content, but the fact that this is possible. Open source projects -- including command-line tools -- can get help systematically understanding users and improving to meet their needs better.

Questions you can answer

As I mentioned last year, I recently talked with David Lord, a Pallets maintainer, who wants to know for his projects:

  • He puts effort into consistent deprecation warnings. Are they effective? Are people seeing those warnings early enough to avoid unpleasant surprises when functionality changes? If not, what could he do to communicate this information to them more effectively?
  • Who’s using this software? That is: do their needs cluster around a few major use cases/workflows? If so, what are they?
  • Which, if any, of the new features from the past few years do they use?
  • How do they seek help? Do they make an effort to start with the official docs, or just search the web and often find old blog posts written by enthusiasts?
  • What level of detail do they need in an error message spouted to the command line, and what would be so long that they’d be more likely to skip reading it?

He's not alone! So many maintainers would like to know this kind of information, but they fundamentally assume it isn't possible. (And I could spend a few paragraphs on why they make that assumption, but I'll skip that today.)

Yet this is the kind of information we got through Superbloom's work.

Example: their research findings helped us improve the format and content of the ResolutionImpossible error message, so users could actually work out what went wrong and how to fix it. UX analyses and training have helped massively improve pip’s user experience design, including error messages and docs, as well as the direct ergonomics of invoking the right commands and having them do what users expect. Another example that hasn't been completely merged in yet: an analysis of some confusing error messages and a suggested template for clearer error message formats.

Join forces

We didn’t limit ourselves to only researching the UX of pip, because that wouldn’t make sense; pip is an interdependent part of the Python package creation and distribution ecosystem, and we needed to understand how users reasoned about, researched, and learned about packaging broadly. And – I believe – learning these tools and facts has been, and can be, helpful to other packaging tools maintainers beyond pip.

And I see this as a model that we can replicate in other ecologies, especially groups of related command-line tools. Pool funds and invest in UX research for a suite of tools that people often use together, and learn surprising and helpful things that help you all improve your projects’ developer experience and user experience.

More resources

I hope this work can inspire maintainers elsewhere to do likewise. You can apply for grants or recruit sponsors to fund this sort of work. Or, if it's easier to learn UX research skills than to hire them, you could learn. Last year, Superbloom published more resources to help you start to do user testing and usability testing in your projects, including:

  • a user testing HOWTO, also available as an interactive guide on itch.io
  • a HOWTO for synthesis (“stage of research in which you reorganize information to make sense of what you observed and heard”)

And the pip work now joins other guidance and case studies in improving command-line UX, such as Command Line Interface Guidelines, and the Rust compiler error style guide.

Hope this is helpful! I’m Sumana Harihareswara, and I can help you with this sort of thing through my consultancy, Changeset Consulting; I do project management, coaching, training workshops, and more. Anyone reading this is eligible for a short free 30-minute consultation call; email me.

And I’m working on a book on managing existing open source projects, so you can learn how to get them unstuck. You can read three sample chapters by signing up for my newsletter.

(This post is a remix of my Fediverse thread and my Python Discourse forum post on the same topic, in case you want to comment in one of those places.)

Comments

Sophia Tolliver
https://motherinlawsex.com/
30 Apr 2024, 6:34 a.m.

Profit comes from owning limits, then charging for them to be calm." --Eevee "In the 50's - 60's they developed a extremely educated and prosperous era of Americans, who then turned all-around and mounted a concerted assault on funds and class electricity. The writers of the clearly show resolved that they had established so a lot of quirks for the character - both of those mental and physical - that the character experienced come to be uncastable. one motivator. But yeah, the particular person who's invested over a decade producing far more than 100,000 Wikipedia edits for no money compensation is possibly in it for the money." --Molly White "There are folks who, yrs in the past, built a preference to support an individual, be a greater human being, advocate for justice, stroll in a protest, volunteer, and demonstrate compassion. In 2005 the present ran Assault on the Media, a contest encouraging listeners to pester a are living broadcast in some way to boost the radio clearly show.

Fidel McGill
https://motherinlawsex.com/
30 Apr 2024, 6:34 a.m.

Profit comes from owning limits, then charging for them to be calm." --Eevee "In the 50's - 60's they developed a extremely educated and prosperous era of Americans, who then turned all-around and mounted a concerted assault on funds and class electricity. The writers of the clearly show resolved that they had established so a lot of quirks for the character - both of those mental and physical - that the character experienced come to be uncastable. one motivator. But yeah, the particular person who's invested over a decade producing far more than 100,000 Wikipedia edits for no money compensation is possibly in it for the money." --Molly White "There are folks who, yrs in the past, built a preference to support an individual, be a greater human being, advocate for justice, stroll in a protest, volunteer, and demonstrate compassion. In 2005 the present ran Assault on the Media, a contest encouraging listeners to pester a are living broadcast in some way to boost the radio clearly show.

Dorcas Damron
https://Camgirlwebsites.com
02 May 2024, 1:18 a.m.

Ranter, Harro. "ASN Aircraft accident PZL-Mielec C-145A (M28-05) Skytruck 08-0319 Walan Rabat Landing Zone". 31 March 2007. Retrieved 22 May 2020. In 2004, Mrs. Gibbons was paid out as a marketing consultant by the Sierra Nevada Corporation of Sparks, Nev., which obtained a no-bid agreement that yr to aid acquire technology to improve helicopter landing devices in desert problems. Retrieved 22 May 2020. The Capitol Hill publication Roll Call noted two several years in the past that of the center's 7 constitution tenants, 5 were being PMA clients whose workers contribute greatly to Mr. Visclosky's strategies. Sierra Nevada, information exhibit, has been among the the firm's greatest-paying customers the past two several years, getting paid out it $280,000 past yr. SNC compensated PMA Group $280,000 in 2006 for lobbying, and PMA was exposed in a huge lobbying scandal. Las Vegas Sun. 8 April 2007. Retrieved 22 May 2020. Most of the cash went to the PMA Group, a mammoth lobbying company in Washington started by Paul Magliocchetti, formerly a best staffer on the House Appropriations protection subcommittee. Web. seven December 2016. Retrieved 28 May 2020. In July 2015 AFSOC introduced it was retiring two thirds of its C-145A fleet, with eleven aircraft subsequently currently being disposed of.

Octavia Headlam
https://Camgirlwebsites.com
02 May 2024, 1:18 a.m.

Ranter, Harro. "ASN Aircraft accident PZL-Mielec C-145A (M28-05) Skytruck 08-0319 Walan Rabat Landing Zone". 31 March 2007. Retrieved 22 May 2020. In 2004, Mrs. Gibbons was paid out as a marketing consultant by the Sierra Nevada Corporation of Sparks, Nev., which obtained a no-bid agreement that yr to aid acquire technology to improve helicopter landing devices in desert problems. Retrieved 22 May 2020. The Capitol Hill publication Roll Call noted two several years in the past that of the center's 7 constitution tenants, 5 were being PMA clients whose workers contribute greatly to Mr. Visclosky's strategies. Sierra Nevada, information exhibit, has been among the the firm's greatest-paying customers the past two several years, getting paid out it $280,000 past yr. SNC compensated PMA Group $280,000 in 2006 for lobbying, and PMA was exposed in a huge lobbying scandal. Las Vegas Sun. 8 April 2007. Retrieved 22 May 2020. Most of the cash went to the PMA Group, a mammoth lobbying company in Washington started by Paul Magliocchetti, formerly a best staffer on the House Appropriations protection subcommittee. Web. seven December 2016. Retrieved 28 May 2020. In July 2015 AFSOC introduced it was retiring two thirds of its C-145A fleet, with eleven aircraft subsequently currently being disposed of.

Etta Jaynes
https://Yagerweb.com/
05 May 2024, 12:28 p.m.

G4 Canada web page Archived November 22, 2018, at the Wayback Machine, which determined as G4techTV right until June 2009. Continued to host Leo Laporte's Tv exhibits (Call for Help, The Lab) until finally cancelled in 2008 soon after sale to Rogers Comm., and shares programming from American-created exhibits from Comcast, Turner Broadcasting and other networks. Owned by Rogers Communications. The easy changeover is a thing that you can normally glimpse forward to due to the fact no time will be wasted from your no cost demo. Justice Merchan has revealed so significantly that he is eager to maintain this trial on plan. But imagine us, with a lot of fantastic end users and an interface that permits you to quickly explore a match, you are a lot more probably to would like to keep this very little courting application all around. Throughout the class of the show's historical past, it has gone by way of a lot of improvements, in additional than just name. They are pretty partaking, personable, and (of system) pretty. The award recipients are mentioned under by the calendar year of the award ceremony.

Teodoro MacNeil
https://Yagerweb.com/
05 May 2024, 12:28 p.m.

G4 Canada web page Archived November 22, 2018, at the Wayback Machine, which determined as G4techTV right until June 2009. Continued to host Leo Laporte's Tv exhibits (Call for Help, The Lab) until finally cancelled in 2008 soon after sale to Rogers Comm., and shares programming from American-created exhibits from Comcast, Turner Broadcasting and other networks. Owned by Rogers Communications. The easy changeover is a thing that you can normally glimpse forward to due to the fact no time will be wasted from your no cost demo. Justice Merchan has revealed so significantly that he is eager to maintain this trial on plan. But imagine us, with a lot of fantastic end users and an interface that permits you to quickly explore a match, you are a lot more probably to would like to keep this very little courting application all around. Throughout the class of the show's historical past, it has gone by way of a lot of improvements, in additional than just name. They are pretty partaking, personable, and (of system) pretty. The award recipients are mentioned under by the calendar year of the award ceremony.