Making Your Open Source Project More Accessible To New And First-Time Contributors

Programming is unnecessarily unfriendly to newer programmers. We can make it better through simple optimizations. This is the Second of a Series of blog posts where I’ll be exploring that!

One of the most challenging and popular topics amongst newer (and especially self-taught programmers) is contributing to open source.

The scope of making your first open source contribution can be extremely overwhelming — especially when so many open-source projects don’t make any significant efforts to be inclusive of new or first-time contributors.

Here’s a list of light-weight suggestions for your Readme.md and Contributing.md files that will make your open-source project accessible to beginners, and build a stronger community around your project*.

Contributing.md:

1. Always have a Contributing.md
2. Git & GitHub hyperlinks: Include Hyperlinks to how to Fork A Repo andIf You’re New To Git**
3. New Contributors Section: Have a “New Contributor Tasks” section (Drupal is a great example!!)
4. Break Tasks into levels: (Easy, Intermediate, Advanced). Tag Easy Issues as “first-timers” or “first-timers-only”
5. Is your “Easy” actually Easy: Realistically Check that your concept of “Easy” is actually easy for newer programmers. If necessary, find outside, newer programmers and get their feedback***.
6. Write Medium.com articles like this one from FreeCodeCamp
7. Make “Squashing Commits” a hyperlink****
8. IRC is a nightmare for newcomers: The visual interface is highly inaccessible, and it’s very confusing to learn at first. I suggest Slack instead. Gitter is another option, though its lack of a Search Field, and unintuitive notification options are barriers to accessibility an enjoyable use.
9. Link to your Docs: If you have multiple sets of documentation, link explicitly to the docs you want contributors to use
10. Explicitly state dependencies: If you have dependencies, special libraries or a specific style guide you use, link to them in a “Before Contributing, Read This” Section
11. Open Issues? Or Just Pull Requests: Specify whether you want people to open Issues for a contribution first, or to just make the pull requests. If the answer is mixed, give examples for tasks that would fall under both sections
12. Who are the project maintainers anyway: Explicitly mention who and where contributors can contact project maintainers or mentors they can ask for help. Explicitly mention who the project maintainers are (or link to a page with their names)

Readme.md:

1. Always Have a Readme.md
2. Have one for every top-level folder: For each major folder in your repo, have a Readme.md file. Explicitly describe the purpose of that section (ie, running scripts to build, or this is the module that does translation, etc.) Break down important sections of the code.

If you have other suggestions to add, or feedback on this list, feel free to leave them in the comments.

tl;dr: Make your contributing.md and readme.md files explicit. Include links to Git/Github Tutorials. Label issues/bugs as “Easy” or “first-timers” or “first-timers-only”. Check Drupal’s guide for reference.

Footnotes:

*Note: This list is just as useful for onboarding new employees at your company or organization.

**I didn’t mention BitBucket or Mercurial, etc. because I haven’t used these, and don’t have the appropriate knowledge for this. The same general guidelines apply.

***I am happy to provide feedback on this. I have been programming for a year, am self-taught and at an early-intermediate skill level

****Sorry — I don’t have a good reference link for this.

Related:

Accessibility In Programming Tutorials, Guides & Documentation

Originally published at lunacodes.wordpress.com on April 2, 2016.