Dear Non-Coders: Rescue OSS from Itself

This post is about how to find open-source projects that could benefit from your time and expertise, and then make meaningful contributions to them - even if you're starting from a blank slate. A blank slate might mean that you have no meaningful relationship with the project, or it might mean that you've never contributed to an open-source project, period. Either way, my goal is to get you rolling in the open-source community =)

Further, while this post certainly applies to software engineers, it's written for people who might otherwise not get involved in a project because their interests and expertise don't reflect the problem that the project is solving. Open-source projects need web developers, UI / UX designers, technical writers, graphic design artists, sysadmins, and pretty much every other role that is valuable, if not critical, to the success of technical projects, too. The same steps for going from "couch" to "contributor" apply regardless of your field.

I've had this post on my TODO list for a while, but what finally pushed me to write it was a discussion that started during The Practical Dev's's weekly #DevDiscuss session a few weeks ago, prompted by a question regarding personal projects. Specifically, about using personal projects to build your portfolio:

I responded with the suggestion of finding & helping open-source projects that need help:

I received several responses asking for guidance about how to do this:

I do want to be really clear that I'm not advocating for "spec work" work, here. This post is meant for people who want to contribute to open source.

So, off we go =)

The Problem

The developer communities that grow around open-source projects are fascinating and exciting in their ability to build amazing software projects. One of their weaknesses, though, is that these communities often reflect a significant bias in the types of expertise they attract. I'll give an example from personal experience.

One of the projects I lead is the GNU Radio Project. As F/OSS projects go, it's probably "medium-large sized". We have a user-base in the high tens-of-thousands, an annual technical conference for which many people travel across the world to attend, and each year many millions of dollars are spent building GNU Radio applications. Due to the nature of the project's objectives, in order to be an expert with it you really need to be technically skilled in a staggering number of fields, including C/C++, Python, signal processing, assembly (for hand-optimized SIMD), analog radio hardware, communications systems design, and Linux - just to name a few. In short, our developers are deeply technical in a lot of fields.

But we can't build a website to save our lives. We don't know how to design UIs, even though the most important tool in the project is a large GUI-based application. Our UX is atrocious. Our documentation is, frankly, horrible, and even when we do try to write some it's barely understandable to most people. Our web infrastructure used to regularly fall on its face. And until one of the core developers put up some of his own money to pay for a logo, our branding was, uh, embarrassing:

Many open-source projects suffer from the same problem. Fundamentally, the issue is that F/OSS project communities mostly attract developers who are interested in the technical areas of the project. So, the Linux kernel mostly attracts engineers interested in kernels, low-level programming, drivers, and the like. Compression projects mostly attract developers interested in compression coding theory and data representation. Graphics libraries mostly attract developers interested in, well, graphics. You get the idea. It's not uncommon for other aspects of technical projects (eg., UI, UX, graphics, web sites / front-ends / applications, technical writing, etc.,) to get neglected or outright dropped on the floor, simply because the project can't find people within its own developer community that have the requisite skills and interest.

This is acutely problematic, and neglecting these things can easily stymie project growth. How likely would you be, as a potential new user or developer, to adopt something with terrible UI, UX, docs, and a website stuck in the mid-90s? These gaps in the project communities' skillsets do real damage the project.

So, circling back around to the original #DevDiscuss question: where there are huge gaps in talent, there are huge opportunities. If you have the sorts of skills I listed earlier, you are in a position to make critically valuable and impactful contributions to important and widely used F/OSS projects. If you're looking for a way to learn something new, sharpen existing skills, build your portfolio, and grow your network, there are few better ways to do it, in my opinion.

Also, I want to highlight that contributing doesn't necessarily need to only be "putting out the fires" or "filling in the gaps". That's likely some of the most urgent work, but you can also propose something new and grand. For example, while building a website for a particular project, you might have an idea for a web-based application that would be of tremendous use to the project's users, which the developers might not have thought of themselves. Open-source communities are driven by engaged people bringing great ideas to the project, and you should feel empowered to bring yours. If you have an exciting idea for a new development you think the project might be interested in, I encourage you to propose it =)

How to Get Involved

So, then, what projects could benefit from your help? Instead of just listing projects, I'm going to recommend a way of identifying projects, yourself, and then reaching out to them to get involved.

Side Note: If someone built a web service that provided a way for F/OSS maintainers to post requests for help (e.g., "we need a web dev!"), I think that would be tremendously useful. There are sites that do this for software engineers, but it's not likely, for example, that a graphics designer is looking for "First-Time Contributor" labels on GitHub issues.

One of the things I've learned about open-source is that people are much more likely to get engaged, make meaningful contributions, and have fun if the project is something they are passionate and excited about, or have a vested interest in its success because they use it regularly.

Couch to Contributor

  1. Identify software you're interested in, either because it's just a cool project or you personally rely on it. The goal, here, is to create a filtered list of projects biased by your personal interest.
  2. Look at the state of the projects' non-core-code resources, like their website, their documentation, their community management tools, etc., Down-select to projects where you think you could make a positive impact.
  3. Next, for these projects, check out the guidelines about contributing / getting involved. Make sure the project is open to outside help (some aren't), and that any license / CLA terms are reasonable. You may need to handle the latter bit as part of the next step.
  4. Prioritize the projects that are left in terms of what you would like to work on, and contact the project maintainers to ask about getting involved.
  5. Lay out an implementation plan with the maintainers, and start hacking =)

I realize my list above glosses over a lot of details, so as an example, I'll go through the exercise, myself:

Step 1: Creating a List

I'm currently working on a vanilla Fedora 26 system, running GNOME. That means, right off-the-bat, I'm using the Linux kernel, the Fedora OS, the Wayland X-Server, a bunch of GNOME tools and daemons, the Pulse audio daemon, and all of the other software that makes my system work. Except for the Linux kernel, I don't personally get excited or feel especially interested in any of those projects, so I would leave them off my list. Moving on to my development environment, I use zsh, powerlevel9k, oh-my-zsh, vim (and occasionally spacemacs), and tmux. When I'm building and developing software, I use tools and libraries like cmake, fftw, Qt, and mako - to name just a few. This is enough for demonstration purposes, so let's check some of these out:

Step 2: Check Out Each Projects' Status
  • Zsh - The website could have been written in the late '90s, the docs are difficult to navigate, and the website really doesn't do a good job of selling the project. The docs are actually kind of hilarious (example).
  • Powerlevel9k - No website, period. The docs are one giant README you have to scroll through, and the project could clearly benefit from web configuration tools but none exist.
  • This one is cheating, a little, because P9k is one of my projects. Come work with us! We have a lot of fun =)
  • Oh-My-Zsh - Looks like they are doing okay, for the most part!
  • Vim - The website is clearly pretty dated. It even carries a warning, The online, hyperlinked copy of the documentation is currently outdated. - I wonder how long that's been there?
  • Spacemacs - Whoa, they even have a web-app version of the editor. They are doing great.
  • tmux - There is no website, and for documentation it refers you to the manpage or the brief README file. It looks like others have created docs (even a book), but things could clearly be improved for the project.
  • cmake - Looks like they're doing okay.
  • fftw - For such a widely used library (it's even used by Matlab), the website is... rough. The documentation is difficult to navigate, and they have a ton of pages filled with benchmark plots (one example of many), but they are difficult to parse and comprehend.
  • Qt - Clearly doesn't need help.
  • mako - Website, docs, etc., all look well put-together. They are doing okay.
Step 3: Inspecting the Contribution Process

Okay, so, from the above, we've down-selected to the following list. Let's check out the contribution status for each one:

  • ZSH - I could not find any public guidelines about contributing to the project. After some searching around, I found this portion in the FAQ about how to contact the maintainers, and based on that, my assumption is that not having clear contribution instructions is just another gap in the docs. So, not a lot of public information, but nothing that's a show-stopper.
  • Powerlevel9k - There is no file, but there are contribution instructions in the wiki that say to file a PR or open an issue on Github. Great!
  • Vim - I couldn't find this through the website, but by Googling for vim contributing I landed on the in the Github repo, which says to use the ViM mailing list for anything that isn't an issue.
  • tmux - The CONTRIBUTING file indicates that the Github Issue tracker can be used for getting in touch, but the README recommends using the e-mail for suggestions and contributions. Sounds like the latter is the way to go.
  • fftw - At the bottom of the website, it says "comments, questions, and suggestions" are welcome, and provides an e-mail address for contact.

None of the projects above say anything about copyright-assignment or licensing requirements, so this is something we'll need to ask the maintainers in the next step.

Step 4: Establish Contact

Okay, so, based on the above, it looks like all five of the options from Step 3 are good potential projects. You don't want to over-commit yourself, so I recommend prioritizing and contacting them one at a time so you don't suddenly end up with 10 active projects.

When you get in touch, I suggest introducing yourself briefly, explain the things you are interested in working on, and ask if the project leads / maintainers are interested in that contribution. If you aren't sure how to get started, here's a brief template you can use to start the conversation:


I am a [web dev / tech writer / UI / UX designer, etc.,] and am interested in contributing to [project]. I think I could help improve / build-out the project's [website / docs / UI / etc] by [doing what].

If the project leadership is interested in this contribution, it would be great to coordinate a bit on a plan for getting it done in the best way for the project. Let me know what you think!


Now, I want to point out that you may get turned down, but that is okay. While you are indeed being very generous in offering your time and expertise to the project, every contribution to a F/OSS project requires the time of the maintainers - sometimes a significant amount of it - and they might just not be able to accommodate you. Everyone has busy lives, and sometimes that's just how things turn out. So it goes.

And, while I wish I didn't have to write this, there are some open-source communities with toxic cultures that can be hostile to unknown developers. If at any point you get a response that seems to indicate this might be the case, don't engage, just walk away. There are many other projects that would welcome your participation, and those are the communities that deserve your time.

If the project leadership is excited about your work, then double-check what they want in terms of copyright assignment and rights. Some projects will require that you sign a Contributor License Agreement (CLA); the Free Software Foundation, who runs all GNU projects does this, for example. Most projects will not require assignment.

You should also be sure that the project agrees with your terms for giving them the code. If as a condition of you making your contribution, for example, you want to be sure that the source code you provide is publicly available under an open-source license and/or you are given attribution, you should bring this up now. Be sure that everyone is on the same page with regard to how your work will be treated once you hand it over. If you and the project disagree, don't be afraid to walk away to the next opportunity.

For most projects, this conversation is super easy, though. Assuming you want the standard "open-source with attribution", pretty much everyone will be on-board since you are already working with an open-source project.

Step 5: Coordinate and Start Hacking!

Next, you need to coordinate an implementation plan with the maintainers to make sure the final product of your work is usable by the project.

One of the most frustrating things that happens in open-source contribution pipelines is when someone spends a ton of time implementing something and then suddenly appears on the mailing list, announces their work, and asks to have it merged. While the contributor probably thinks they are being tremendously generous, this can be a nightmare for the maintainers. Since the implementation was done without input or guidance, there is no guarantee it's usable by the project. If the contributor made decisions that aren't compatible with the project and the work is not usable, this often ends in the maintainer feeling rejected and walking away and the project missing out on what could have been an amazing contribution. This can easily happen if the contributer broke an abstraction layer they didn't know about, introduced a dependency the project can't support, or used a tool that is incompatible with the project's infrastructure - just to name a few.

It is critical that you plan out your work with the project leadership to make sure it is usable by them once you are done.

Now, you've got a project that's excited about your work and plan to get it done. It's time to start hacking and having fun =)

Wrapping Up

Contributing to an open-source project really can be an incredible experience and opportunity. You're guaranteed to learn from your work, grow your network, and create something that many people will use regularly and benefit from. And, when you're done, in your portfolio you can point to it as an example of something you've built that is used by people all over the world to get things done.

If as part of your work you conduct interviews, gather requirements, and create design documentation, that's great experience that goes beyond just writing code. Also, and I don't think I can stress this enough, knowing how to work and collaborate with open-source communities is a really valuable skill that can open doors you perhaps wouldn't expect.

If you have any questions, feel free to get in touch with me. Otherwise, have fun, and Happy Hacking =)

Ben Hilburn

Ben Hilburn

bits, nibbles, bytes, and words
D.C. Metro Area