December 17, 2021

5 book recs, internship program tips, and a holiday on Dec 21st

Hi, newsletter subscribers! Thanks for being interested in Changeset Consulting and my open source project management work, including the book I’m writing with advice for maintaining legacy projects.

This is my fourth and last newsletter of 2021. I’ll share a bit more of the book in progress, recommend a few books that have influenced me, and tell you about a few useful tools and resources.

(For hyperlinks, view as HTML or see the archived version on the web at https://buttondown.email/Changeset .)

Five book recommendations

Five books that gave me specific tips or facts that help me manage open projects better.

1. “Switch: How to Change Things When Change Is Hard” by Chip Heath and Dan Heath. Switch has a lot of good ideas and case studies about how to change institutions, companies, families, and yourself. In particular it helped me get better at initiating pilot programs, accepting the kinds of support I sometimes need to form better habits, and appreciatively noticing “bright spots” so I can replicate success. It was so accessible and smooth that I was a little suspicious and envious, as a writer. I bet you’ll find ideas in here that will help you in your everyday work and community. (Note to Jacob Kaplan-Moss: I know you had particular things you didn’t like about the examples in Switch and look forward to your book review so I can link to it!)

2. “Missing Class: Strengthening Social Movement Groups by Seeing Class Cultures” by Betsy Leondar-Wright. Leondar-Wright’s article “It’s not ‘them’ – it’s us!” is a great sample of the insights in Missing Class, helping us notice when the entrenched habits of an in-group make it harder for us to really include people from different cultures. How do we meet people where we are, and bring more diverse perspectives into our work? If you liked my “Inessential Weirdnesses in Open Source Software” thoughts then it’s worth reading Missing Class to get deeper.

3. “Lower Ed: The Troubling Rise of For-Profit Colleges” by Tressie McMillan Cottom. McMillan Cottom’s article “The Coded Language of For-Profit Colleges” is a good introduction to the arguments and case studies you’ll find in Lower Ed. This book helped me understand the labor market and academic environment that causes a lot of people to come into open source, or sign up for code schools and bootcamps, in the hopes of class mobility. If you liked the Q&A at the end of “What Would Open Source Look Like If It Were Healthy?”, “Lower Ed” was an influence.

   Note: I particularly want to recommend Lower Ed to people involved with Google Summer of Code and similar paid internships, and experimental learning institutions and clubs. You may not think of yourself as an educational institution, and you may even try really hard to brand yourself without the word “educate” or any of its derivatives showing up in what you say about yourself. But you ought to know the landscape you’re in, and the reasons for the credentialism you may scorn, and how your choices around accreditation, tuition, participant debt, credentialing, and vocational focus may differently affect participants of different classes and races. Yes, this applies to Recurse Center, I say, as a Recurser.

4. Finally, two by Greg Wilson! “Making Software: What Really Works, and Why We Believe It”, an anthology of research edited by Andy Oram and Greg Wilson. Skim at least the table of contents and you’ll see something that will help you work better and/or win an argument. I used the research in this book to improve MediaWiki’s code review processes, Zulip’s documentation, and pip’s new developer onboarding.

5. And Wilson’s “Teaching Tech Together: How to create and deliver lessons that work and build a teaching community around them”, a guide to effective instruction, is a valuable reference as I develop documentation, trainings, and more. “We have been talking about mental models as if they were real things, but what actually goes on in a learner’s brain when they’re learning? The short answer is that we don’t know; the longer answer is that we know a lot more than we used to....As scary as it is, we are the grownups.” Greg, your relentless pursuit of actual maturity in our field is a lodestar for me; thank you.

The book

I’m working on a book to teach you what I know about getting open source projects unstuck. At the end of 2020 I released an ebook sampler with three chapters from the full, forthcoming book. It’s free for anyone who subscribes to this announcements mailing list (as a subscriber, you should have gotten an email with a download link).

If you’d like to get more frequent samples of my work in progress, reply to this email and say so. I only send the newsletter out 1-10 times per year, so I’m thinking of starting a private list where I send some snippets about once a week.

Here a work-in-progress excerpt on running or mentoring in Outreachy, Google Summer of Code, or similar apprenticeship programs:

Internship programs: pitfalls and ways to improve

We ask inexperienced managers to mentor these interns, sometimes as the first time they’ve ever managed anyone. But managing someone remotely, especially when they are new at the task, especially when they may have never had a job before, is very difficult....

People who have never had a job before, in general, do not have professional skills. They’re worse at finding a good middle way between asking for help all the time and haring off into long silences and coming back having done the wrong thing. They struggle more to distinguish between critique of the work and criticism of them as individuals. They are more likely to forget to show up for meetings, or to tell you ahead of time that they’re taking vacations. They are more likely to get embarrassed about mistakes they’ve made and hide them. They don’t know which paperwork is crucial so they cause headaches by missing deadlines. And, when someone else makes a mistake that affects them, they likely won’t have enough context and experience to judge when to escalate the problem to someone who can fix it.

And people who have never contributed to open source software before have trouble, beyond simple ignorance of tools like git, with the social dynamics. They may be reticent to work in public, to the point of delaying pushing their work for review and risking data loss by working on private local branches for months. They have much more trouble distinguishing between feedback they need to pay attention to and feedback they can brush off, especially based on who’s saying it and whether they have influence in the project. And they struggle more in finding an appropriate tone in making public suggestions and criticisms, and in calibrating what tone they should expect from their colleagues.

Managing someone remotely makes the manager work consciously and explicitly to avoid certain pitfalls that look more obvious when working co-located. A co-located manager can, without as much additional effort, notice when a new contributor’s facial expression conveys frustration during a task, or loop them into both formal meetings and informal conversations to convey both urgent information and general working context. A co-located manager can review work in person, transitioning fluidly among conversation, work on a shared screen, and paper or whiteboard sketching to illustrate a point......

It takes time to run one of these programs well, but if you run one badly, then you end up with unmergeable code or other work, a disappointed participant who won’t come back as a volunteer, and time taken away from other work. And people will likely say “we tried it and it didn’t work” instead of “let’s try it again differently next year”. If you run it well, it will take more time. But that time investment will pay off with a co-maintainer, and eventually with a stronger codebase and project.

Some ways to improve your internship/apprenticeship programs:

• Ask yourself: have you mentored or been an intern in a program (inside or outside of open source)? What worked well? What did the program achieve that an unstructured approach would likely not have achieved? What could have been better?

• If you’ve never mentored a telecommuting internship before, start by co-mentoring on a different project, even one where you are not a codebase expert. You can still coach a participant on general free software procedures, help her manage her time and bounce ideas around, etc. This is especially welcome if you’re closer to her time zone than the main mentor is!

• To get better at understanding what it’s like to be a novice open source contributor so you can teach them the skills they’ll need, practice. You can use the Carpentries curriculum to teach a neighbor or family member the Unix shell. If you had a lot of trouble making this work, read Teaching Tech Together for in-depth teaching advice, and try again.

• Look at your codebase and developer workflow and find idea seeds for intern projects. If you notice stuff that needs doing but isn’t in your issue tracker yet, great, add it in there. Finding “low-hanging fruit” is fine, but think more broadly too about what levels of capability newcomers might have.

• Think about how long it would actually take someone to implement these things, and scope down; if the internship period is twelve weeks, scope for something you think “should” take 6 weeks, to allow time for testing, bugfixing, documentation, review, integration, and hiccups.

• The top predictors of interns’ continued interest in staying with the community after their internship are the mentor relationship and how substantial their interactive engagement with the larger development community was. So: select mentors based on a judgment of their collaborative and mentoring skills, set up frequent public online meetings for students and mentors, and insist on early and frequent public communication from students. This means that you may ask certain potential mentors not to serve, and that you may decide against selecting students or student-mentor pairs because you judge them unlikely to succeed.

Interesting links

• December 21st is the next Volunteer Responsibility Amnesty Day: Every solstice, take inventory of your volunteer responsibilities. Check with yourself, and end the commitments you need to end – maybe by taking a break, or by rotating it on to someone else, or by sunsetting a project.

• Zulip, an open source group chat service, announced: “Zulip will not integrate a crypto asset wallet, issue crypto assets, promote NFTs, or otherwise attempt to profit from the crypto asset gold rush. We believe that doing so would inevitably compromise the integrity of our 100% free and open-source project.” I applaud this announcement and would like to see more institutions making this commitment.

• “Why you shouldn’t invoke setup.py directly” for people who have to do Python packaging stuff: “Despite the fact that no one will read more than the next 3 paragraphs, I hope that this article can be useful when you want to advocate against the use of setup.py: when you make a PR or a comment in a Slack channel, you can link to this Proustian monstrosity and hope that your audience pales before the prospect of reading through the whole thing and just assents to whatever you’re asking them to do.”

Tools

• “pip-audit is a tool for scanning Python environments for packages with known vulnerabilities.”

• Waveform’s Bufferbloat test helps you figure out whether bufferbloat is slowing down your Internet connection, so you can fix it.

Best wishes, as always.

– Sumana Harihareswara, Changeset Consulting