Blog by Sumana Harihareswara, Changeset founder

21 Apr 2022, 12:15 p.m.

Nurturing Volunteers: A Shortcut And An Event Template

A few suggestions to help you nurture volunteers in your projects. (Expanded from some advice I recently gave Ms. Boba, founder of BobaBoard -- she's a coaching client of mine.)

Live Tour As First Draft: Extract Tacit Knowledge From Your Brain

New people stumbling around a complicated system need to understand why it exists, what the major components are, and how stuff flows through them. That's the kind of context that you already have but that can be difficult for you to document because you know it so well that it's soaked in past conscious perception. This applies to a complicated piece of a codebase, the interrelationships among different government agencies, a multistep publishing process -- anything where a newcomer gets confused about who/what does what and why and how they can start using/working with/improving it. They'd love to read a "what is even going on here" guide, but you try to write it and you stare at the blank page because you don't know how to start or how to structure it or how much depth to go into.

A quick-and-dirty workaround to get your first draft started is to use an audience. Get a volunteer who genuinely doesn't know this stuff yet, and have a synchronous conversation with them where you give them a tour of the system. Explain what they need to know, and have someone take notes along the way -- or record the conversation and get a transcript. The learner's questions will help keep you on the right track and show you what your guide will need to cover. The notes or transcript of the tour and the Q&A now serve as raw material you can edit into the first draft of your guide.

Some learners are eager interviewers and arrive with appropriate questions. Don't count on it; you should assume that you need to initiate the overview. How should you structure it? What story do you set out to tell? I've found three main ways to approach this:

  1. Historical. This is good for legacy systems that have responded to significant change by accreting layers. Go chronologically and divide the history into stages, listing major events and trends and decisions, and giving your audience snapshots of the system as it grew and changed in response. For example, I recall Katie Horn's "Fundraising: Under the Hood" presentation (video) explaining how the Wikimedia fundraising system grew. The imagined listener is a Wikipedia editor or reader who has seen those fundraising banners and maybe donated. Horn explains the system that displays those banners, interacts with payment gateways so donors can donate in a zillion currencies and countries, prevents fraud, double-checks the accounting with payment processors, and notifies everyone of everything. Horn demonstrates why and how a big system works by helping you see all the problems that the components solve.
  2. Organizational. This is good for human systems or for repositories with lots of top-level directories (this is how we started the architecture section of the pip documentation). Go breadth-first and explain what the major divisions/components are and what they do, and the social norms or policies governing how they relate to each other. For example, when new people show up at your company, you might draw the org chart on a whiteboard to walk them through: who are the eight directorates in this engineering department, and who are other important stakeholders outside the department, and who's responsible for what? This helps new employees better understand their relative positions, and what kinds of requests they can expect and from whom -- which means they'll be better prepared to understand which unexpected messages should raise alarms.
  3. Experiential. I've saved this for last because I think it's pretty widely applicable and a good go-to approach for nearly any system. Explain the common case of how something moves through the system (data, money, blood, a bugfix, etc.) from beginning to end, and then add caveats about exceptional cases and how the system deals with them. For example, a common interview question, "What happens under the hood when you go to in your browser," asks you to tell a story like: From the point of view of a single GET request, here is the desired and usual flow of data, from entering the system (the user hitting Enter) to exiting it (the browser receiving the page and rendering it), along the way describing the functions of major components such as the browser, router, and web application. Next: what's enforcing the rules? What are possible attacks or failure points (such as monster-in-the-middle attacks)? And what defenses are built in to resist or recover from attacks or failures (such as TLS)?

The classic think-aloud demonstration is also an example of the experiential approach. At Wikimedia, to help volunteers understand the development process, I ran a live demo of how to fix a bug, including finding the ticket in our bug tracker, investigating it, making the git commit, getting it reviewed and merged, and closing the ticket. At each step, I explained what I was doing and why. If the system you're trying to explain is a component of your codebase, you could run a livestream and narrate yourself adding a feature to that component; Zulip's developers have done this in text chat in their "live coding" channel several times.

Whatever your tour approach, limit the conversation to no more than an hour. This'll help you focus on the main topics without wandering onto tangents, help the audience focus their questions, and reduce how overwhelming the transcript will feel when it's time to edit.

Career Hour: Introduce Learners To Other Projects And Positions

Newcomers often struggle to figure out what tasks they could do and what roles they could aim for ("contributor pathways").

Years back, I was the person in charge of Wikimedia Foundation's open source apprenticeship programs (our participation in Outreachy and Google Summer of Code). One time, I told our mentors to please ask their mentees which open source skills they were particularly interested in learning, so we could try to give them specific opportunities to grow those skills. One mentor reported back to me that his mentee said: I don't know, because I don't know what skills exist that I could learn! What's there to learn?

Well, that's fair. How can you know? So, to address this, I set up some live virtual panel events to introduce our interns to a variety of roles in open source. It was a bit like the "Career Day" presentations that happen in schools, where adults give students short speeches about their jobs. We called them "What's There To Learn?" (transcripts available). In each one, 4-5 representatives from different open source organizations each spoke about the big picture of their organization's workflow, various activities that have to happen for their software to get made and used, and what they specifically did. And of course there was time for questions and answers.

These events did a few things. Interns who had bare-to-no understanding of what a release manager, designer, user experience researcher, performance engineer, marketer, systems administrator, or tester does got to understand the role -- and the skills it takes -- in the context of making software together, so they could form ambitions to learn those skills. They could compare their own project with others, to better understand what was unusual and what kind of process they might like better. And it gave them some specific contacts they could email later.

You can do this too. Contact a few of your contacts in other organizations to ask them to speak in a one-hour Career Hour virtual event. Try to get 3-5 people, and aim for some variety: code-focused and process-focused roles, large projects and small, serving different kinds of users, and so on. Publicize it to contributors in all your and their open source projects to get cross-pollination in the Q&A. If you're doing this during internships like GSoC and Outreachy, tell mentors from other orgs -- if the first Career Hour works well, share the template with other organizers so they can run more, in different time zones.

Changeset Can Help

If these tips sound good to you and you think "Someone with this point of view could perhaps be helpful as we improve our open source project," please check out my consultancy, Changeset Consulting! Very happy to have a free initial conversation. You can also subscribe to my very low-frequency newsletter to get more stuff like this 1-10 times per year.