Skip to content

Becoming a welcoming open source project, Mentoring Branch

Cate Huston (@catehstn) asked what we could do that would get us from “open source” on a project to “welcoming source”.  Codes of conduct, good newbie issues and good onboarding were her initial suggestions, and I said that a good project would also have a really clear goal, because one of my consistent frustrations with trying to start a project is not understanding what the end goal is and how my contribution furthers that goal.

Then Cate got distracted by “jet skiing” in “Suva” (a likely story), and Mike P (@snowcrashmike) and I went down a rabbit hole about mentoring.

Read the context on Storify

Mike said that senior mentoring was also important, and I agreed, but I thought that was too vague. As I see it, there are four kinds of mentoring on a project.

  1. Mentoring on the project itself — architecture decisions, goals, dead ends that we rejected. This should not be mentoring, this should be DOCUMENTATION. (You knew I was going to say that.)
  2. Mentoring in the art and practice of contributing to any project — interpersonal politics, how not to show fear in the face of code repositories, how to figure out who knows where the bodies are buried.
  3. Mentoring in a specific skill or language that is used on the project.
  4. Career mentoring, which is a catch-all for everything from “how to report bad behavior” to “don’t show up to interviews in a shirt with holes” to “plotting your ascent to the corner office”. (Hah. Pretty sure OSS projects are not rife with corner offices.)

I asked Mike which of those he meant, and we agreed that the ideal mentor would be one who could do all of that. Full-stack mentoring, as it were.

But just like full-stack developers are pretty rare, so are full-stack mentors. Asking someone to have that high level of competence on top of asking them to have a product vision, a genius for distributed management, and a competence at coding just seems like too much.

The best solution would be for people who are already in the project to do some thoughtful discernment about what kinds of mentoring they are good at. For example, I can’t code, and my design sense is marginal, but I can write a pretty mean sentence, walk someone through writing a conference talk, and my problem analysis skills are pretty great. So you shouldn’t really have me do pair programming or mentor by teaching a coding language. You should have me mentor someone on how to come across like less of a jerk on mailing lists. I should be mentoring people on how to write bug reports. I can toss code questions over the wall to someone who understands the code base.

The problem is that of course there are not enough mentors. There are not enough anyones, in open source. That’s just the nature of the beast. So when we say that newbies need mentoring, it’s true, but it puts enormous, unreasonable pressure on the very core maintainers we are trying to prevent from burning out.

Asking someone to repeatedly perform something that is not just outside their skill set, but outside their interest is asking them to do a lot more work than asking them to do something they are strong at and pleased by doing. We all need to develop our growing edges, but I feel like that’s not what this is. Instead, it’s an accidental burnout accelerator, because the people who care most about mentoring are the ones who are going to overextend themselves trying to be everything to everyone.

Let’s not burn out our best mentors.

Instead, here is my suggestion for when a project decides to include new contributors:

  • Document the decisions that you’ve made about where you’re going and where you’re avoiding.
  • Be clear about your goals for the project.
  • Establish not just a code of conduct, but a standard of communication that the project tends toward. Lots of smilies? Bullet points? Simplified English? Bilingual postings? Whatever it is, make sure it’s something the core maintainers are willing and able to do all the time.
  • Mark newbie-friendly bugs, features, and doc requests. Try to attach a mentor to the bug/feature/doc. That way, the load gets passed around, and new people get to work with a lot of team members.
  • When a new person asks for mentoring or seems stuck, ask them what kind of help they’re looking for. They may not know, but they can usually tell if it’s a code problem or a people problem.

Tl;dr: Treat mentoring more like a microservice and less like a monolith.

Heidi Waterhouse

Heidi is a mercenary technical writer and travelling salesperson of better process and product thinking. She loves writing herself out of a job and teaching people to save themselves from future pain.

Upcoming appearances

Velocity Berlin
Minneapolis DevOps Meetup
DeliveryConf

Scroll To Top