or how to spread the word and win contributors
Hello folks! Congrats to those who made it to the 4th part of the Open Source journey! For those of you who haven’t read the previous parts or are wondering what I planned for the next parts:
Table of content:
- Intro
- Starting a project
- Documentation
- Publicity
- Issues and PRs (WIP)
- Automation (WIP)
- Versions management (WIP)
Recap
We’ve already discussed what it means to start a project, how to do it optimally and how to write good documentation for it.
Today we’re moving forward and we’ll be discussing how to attract the publics attention to ones project and optimizing it to both attract and correctly manage contributions.
The baseline for this part is:
You already have an open source project, it is available on GitHub, well documented and can be consumed easily via one of the package registries.
Spreading the word
Let's address the elephant in the room: as your project grows you simply wont be able to handle everything by yourself.
Hence, you need more people to work on the project if you want it to live long and prosper.
To get more people involved in your project you need more people to know about it and above all else to believe in it.
From my experience the best way to expose your open source to the right audience is to use one of the well known resources and to write a blog post about your project. The resource might be purely dev oriented (like dev.to) or not (like Medium), or tech focused (like here on Hacker Noon).
One commonality between all these resources is that they have an established audience and it is the relevant audience.
You can also cross-post your article between various online resources so that you’d cover an even larger audience but be aware! Cross posting has a few downsides:
- Each of these platforms may have a different mark up language and you’ll have to redo all the formatting
- Maintenance — if something changes (and things will change) you’ll need to update your blog post across all of the resources.
If you go for Medium I’d highly recommend you submit your article to one of the large publications. It will require additional effort on your end, since you’ll have to align your article with the publication requirements. However, it will also ensure that your article is exposed to a large and, which is even more important, relevant audience.
You can also decide going behind a metered paywall: "Stories that are part of the paywall are also eligible for distribution to Medium readers through topics, which power recommendations on Medium on our home page, on our topic pages, in our Daily Digest and in our apps..."
I can’t tell you which one is better, but my personal preference is publications because it ensures your article is exposed, instead of the vague “eligible for distribution” term.
If your blog post goes viral then it can create a cascading effect and add even more leads to your open source. For example, if after publishing the article your Github project received a few dozens of stars in one day it can get to the Github Trending page which is in itself another source of exposure.
A few points to make your blog post great (again):
- Start with a problem statement. It might even be the title of the blog post.
Usually people are looking for a solution to a specific problem and before they decide investing the time to read your post they should have an idea whether it’s what they’re looking for.
An example: https://medium.com/angular-in-depth/customizing-angular-cli-build-an-alternative-to-ng-eject-v2-c655768b48cc
As you can see it doesn’t say “custom-webpack builder — a new fancy project”, it clearly states the problem that it solves in the title.
If you google “Customizing Angular build” this is the first result you’ll get and right from the search page you can see which problem it addresses. - Describe why and how exactly your project solves this problem
- Provide a detailed step-by-step guide, starting with installation and finishing with a working example.
- Create an example project that uses your open source and link to the sources in the blog post.
There are lots of developers who prefer a working example to any blog post. - Get some feedback before publishing it.
Make your friends go over it without telling them what it’s about and see if they can figure it out themselves. If they can’t then probably it’s not that clear and you need to elaborate.
After you’ve published your blog post, make sure you share it on social media, with your friends, your family and strangers on the street.
This will increase your project’s exposure but you also have to make people want to contribute to your project.
Making your project attractive to contributors
The best thing is to start an open source with other people. This way from the very beginning you have a team with which you can split the burden.
However, that’s not always the case.
However, that’s not always the case.
If you started alone you have to attract contributors and in my experience there are two types:
- Someone who wants to make an impact and looks for a project to contribute to (these are rare but still exist).
- Someone that uses your package and found either a bug or lack of certain functionality.
In both cases just having your source code shared on Github and a single blog post on how to use it are not enough. Here are a coupe of things that can make people want to contribute:
- Have a pending implementation list. It might contain known bugs, planned features or something else.
This list will make it simpler for contributors of type #1 to pick the right item and issue a PR.
It can be a standalone list or you can (and probably should) use issues and labels on GitHub. - Have a contributors guide.
A very basic contributors guide should explain the repository structure and have a step-by-step guide for building and running your project and tests.
The expanded guide can contain architecture, design decisions, code of conduct and more.
A good example is Atom’s contributors guide .
Don’t underestimate it’s value! It’s something that takes a decent amount of time to make when the project has grown, and I wish I created it at the very beginning and updated it gradually as the project evolved.
Unfortunately, I didn’t have someone to point out its importance, and today my project has no contributors guide.
It’s always on my TODO list but there is always something more urgent than that. - Recognize your contributors
Listing your contributors on the main page of the project would give them additional incentive to make a contribution.
Just adding user names can be enough, but I’d recommend you to use All Contributors. Apart of creating a fancy section with profile images and badges for your all your contributors, it automates new contributors addition by creating PRs that add contributors to this section.
Wrapping it up
In this part we’ve discussed several things that will increase your project’s exposure and provide people with an initial incentive to open a PR or an issue.
But this won’t keep them as contributors neither will it make sure they will finish the work they started.
In the next chapter we’ll discuss how to manage Issues & PRs as well as how it affects the peoples’ perception of your project.
If you enjoyed my writing, learned something new or insightful or if you just don’t want to miss the next part, make sure you’re following me on Twitter or here. Cheers!