Creating a Contributor Experience for Humans

In preparation for the wonderful Open Source 101, I wanted to challenge my assumptions on what makes a great contributor experience by asking.

The Twitters answered in force.

Just some of the thoughtful responses. Check out the full thread to learn a tonI highly recommend scrolling through the thoughtful replies yourself. Here is a summary for those looking to make a great contribution experience:

  • Easy of contribution — integrated tests, issues tagged with levels of contribution levels, Easy getting started (Dockerfile), reference docs.
  • **Engaging maintainers **— kindness, responsiveness, constructive feedback, thoughtful changelogs, personality (emojis were mentioned more than once 😀).
  • Clarity of purpose — a clear goal for the project (what it is and isn’t), code of conduct, straight-forward license. Those of us who support maintainers have an opportunity to communicate these user requests and reduce the friction of their implementation.

My Takeaways

I found a few points hit home for me in unexpected ways.

Documentation, but with a twist

Documentation makes or breaks a project’s success for many contributors. The essentials of a Readme, Contributing and License capture what GitHub recommends by default, and there are opportunities to improve them all. I was struck by a couple of the specifics ideas, like the request for a single page contributor guideline. There’s something to be said for brevity.

I love the fact that changelogs were a top request, too:

On that latter point: if you like to learn by example, here are two great examples changelogs that came up during the discussion:

Help them help you

Many people scrolling through GitHub want to help out. I appreciate Mark’s reminder to help make that a little easier. GitHub also provides added visibility to help wanted and good first issue labels on repositories. These two get highlighted at the top of a the projects /issues URL. See the guide here.

Welcoming Maintainers

The verdict is out: In our time of social polarization, contributors have little patience for unwelcoming maintainers. I know it can be a challenge for maintainers to be chipper all the time, and maintaining lots of code is time consuming, so there has to be help on this front. I cannot recommend GitHub’s saved replies or tools like TextExpander enough. Here’s why:

It takes a lot of words to repeatedly be kind to new contributors, and it’s easier to be more human by saving them as default replies. It helps new users feel welcome while removing the dullness from the maintainer. The irony of default replies as more personal is not lost on me, but I promise it’s effective.

Another Worthwhile Read

One of the replies came from the Shubheksha, who wrote this incredibly thoughtful piece:

How to attract new contributors to your open source project
*It’s hard to attract contributors to your FOSS project — especially contributors who are new to open source.*
#### And Thanks

I’m thankful for everyone’s contribute to this thread. If you have more thoughts on Open Source, check out to dive deeper into recommended practices.

This article was originally published on Medium