Blog by Sumana Harihareswara, Changeset founder
Nurturing Volunteers: A Shortcut And An Event Template
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:
en.wikipedia.orgin your browser," asks you to tell a story like: From the point of view of a single
GETrequest, 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.
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.
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.
28 Apr 2022, 6:06 a.m.