Marketing for maintainers: Promote your project to users and contributors

Congratulations: You’ve pushed your code to GitHub. But if you want other people to benefit from your hard work—or contribute back to the project—you need to get the word out. Not only that, but you need to explain why other people should take the time to learn and potentially contribute to your project.

It can be intimidating to go from writing code to writing marketing copy, so The ReadME Project’s senior editor Klint Finley gathered three experts to answer your questions about how to promote your project to both users and contributors. Let’s meet our panelists:

Segun Adebayo is a GitHub Star and software engineer at Vercel. He’s a design engineer and the creator of Chakra UI, an accessibility-focused React component library, and a collection of framework-agnostic UI component patterns called Zag.

Tasha Drew leads VMware’s xLabs, an innovation acceleration lab. She’s also co-chair for Kubernetes’ Working Group for Multi-tenancy, and the co-chair for Kubernetes’ special interest group (SIG) Usability. She likes to play Hearthstone, read novels, surf Twitter, and is a fan of puppies, kiddos, beaches, and picnics.

Aaron Francis is a marketing engineer at Tuple. He’s also an active contributor to the Laravel, Vue.js, and Tailwind ecosystems. He created the serverless Laravel deployment tool Sidecar and Airdrop, which aims to speed up deployment by skipping asset compilation whenever possible.

Klint: How did you spread the word about your project in the early days? Any tips on making something stand out?

Segun: After launching Chakra, I spent two or three months just talking about it and tweeting about it. I shared screenshots to show people what it could do for them. I created 10-20 second demos to show people how easy it is to use, how quickly you can go from zero to launch. That created curiosity and made people want to try it for themselves.

I think when you’re first starting out it’s really important to think about the problem your project seeks to solve. You need to let people know what tangible benefit your project provides, whether that’s helping them work faster or saving them money or something else. When you solve a meaningful problem, it makes an emotional impact. I talk about the idea of the “minimum viable audience,” which is generally just a few friends who can provide honest feedback on something either before it launches or soon after. They can let you know if you’re really solving a meaningful problem and how to make your project more helpful. Also, you should think about how you define your success. I’d say think less about npm download metrics or GitHub stars and think about the impact it makes over time.

Tasha: When you’re preparing to launch your open source project, it’s helpful to think about it through the lens of the people who you expect to adopt it. As Segun said, make sure you are solving a problem for them. If you expect enterprises to adopt it, think about what business problem you’re addressing. Knowing where you fit in the ecosystem is important.

One thing to consider is whether you’re a leader or a challenger. Kubernetes was backed by Google, but was still a challenger. They had to convince people to use Kubernetes instead of one of the existing solutions like Docker Swarm or Mesosphere. Now Kubernetes is a leader and Nomad is a challenger.

If you’re a challenger, you can probably afford to be more open, both in terms of accepting feedback and in terms of how flexible and extensible your software is. Or you can think about a niche problem, and solve it significantly better than the leader. What you want is for people to have a reason to try you.

Aaron: Solving a niche problem worked well for me when I launched Sidecar. It’s a general-purpose tool and it can be hard to get people to use those. To get the word out in the early days, I picked a very specific use case that Sidecar could solve really well. Basically, I provided an easy way to use Inertia.js to do server-side rendering with Laraval’s Vapor service. That got people in the Laravel and Inertia.js communities talking about Sidecar. Addressing the problems of existing communities is a powerful way to get noticed. You have to advocate for yourself, you have to reach out to podcasts, meetups, and conferences. You have to tweet at people and let them know that you have a solution to a problem they’ve mentioned having. You shouldn’t feel icky about it. You put a lot of time into making something helpful.

Besides that, documentation is crucial. I will say if you want people to use your project, you need to make it as easy to adopt as possible, and the best way to do that is through documentation. Write as much of it as you can stand to write. It lowers the barrier to entry for your project and can make the code itself better. For example, if you find it’s hard to document a particular feature, that’s probably a sign that it’s too complicated and you need to simplify it.

Segun: And don’t stop with written documentation. Video is really helpful for a lot of people. People learn in different ways so it’s important to provide different types of content.

Klint: What are some common mistakes people make when trying to communicate the value of their open source project?

Tasha: Sometimes you’re so excited about what you built that you over-fixate on how clever you were. For example, I’ve seen project landing pages with links to distributed systems papers and information on how they implemented a particular protocol. That sort of information is only interesting to other distributed system builders, not to users. You need to think about what problem you’re solving, not give a dissertation on the technology you used. What’s the message you want people to take away from your webpage or your README? It’s probably not related to the theory behind the code.

Segun: Yes, one of the biggest mistakes I see is the use of too much technical terminology on a page, focusing too much on the features rather than the tangible benefits it provides to users. It’s best to talk about the “why” or motivation behind the library, then show your users what benefits they stand to gain by using your library. And doing all that in as simple a language as possible.

Klint: But if what you’re working on is a tool for developers, or if you’re trying to attract contributors, does it make sense to focus more on the underlying technologies used?

Segun: That helps, but it’s important to note that people who want to contribute to your project have varying levels of skills and expertise in the technologies you’ve used. Some might be interested in contributing to documentation, others might want help with triaging, fixing bugs, etc. That said, ensuring your project is easy to contribute to by providing clear contribution guidelines, creating walk-through videos, and reducing the “setup” processes go a long way. Documenting the roadmap, currently known bugs, and even asking for help in certain areas will help attract contributors.

Tasha: The other thing to remember is that you probably want to attract non-technical contributors, and contributors of different technical skill levels. To go back to my earlier example: If you have a sophisticated distributed systems project, you shouldn’t expect to get a lot of people with deep distributed systems experience to contribute to your project right away. That’s probably going to be a big commitment of time and effort and in the lifespan of your project, you’ll probably only ever get a few people who will contribute to those parts. Most of your contributors will be pitching in other places, where the barrier to entry is lower. You want to make your language and project easy to understand so that people of various technical skill levels will be interested.

Aaron: I think as developers, we become attached to the things we build. That’s not a bad thing. But you shouldn’t become so invested in the thing you’ve built that you insulate yourself from feedback. It’s easy to reflexively dismiss criticism and think “that person just doesn’t get it” or “they’re just not smart enough.” There are trolls out there who will just say negative things to get a rise out of you, but there are also a lot of well-meaning people who just want to understand what you’re building or learn how to use it.

Klint: What can maintainers do to attract more contributors in the early days of their project, when it’s too early to say “Hey, this is a big project, you can put it on your resume”?

Tasha: You will get more contributors if you get organic user growth. If people see it as something useful, if they see other people using it, they’ll want to contribute. The more valuable your project is, the more people will want to get involved, whether that’s because they love the project or because they see contributing to it as a way to advance their careers.

Also, you want to make it technically easy to contribute. You can lower the barrier to entry by designing your software for extensibility. Take Chef for example. People can contribute Cookbooks to the Chef Supermarket without having to understand the inner workings of the core software. Your software will be more useful if you let people build their own extensions without having to get a pull request approved, and the community will grow faster.

Aaron: The big thing is to be responsive, especially to the first few people who are taking a risk by investing time in your unproven project. Time is finite, we only get one life, so value those people who are willing to spend some of their precious resource on you. That applies not just to people sending pull requests, but to people pointing out problems or making suggestions on social media as well. Thank people for pointing out problems, thank people for making suggestions even if you don’t plan to implement them right away, and acknowledge parts of the software that might be painful right now. The situation is super different when you’re the size of, say, Tailwind, and you’re getting hundreds of issues per day. But if you’re starting out and looking to get traction, you need to be kind, responsive, and helpful. Kindness is key. You can’t always be responsive or helpful but you can always be kind.

Segun: I agree—you have to be responsive, kind, and helpful. Knowing that people are willing to spend their time improving your project and pushing your vision forward is a good perspective to have. Don’t be rude or mean to people regardless of their comments or feedback. You also need to get comfortable interacting with strangers, whether it’s via text or video chat. Be ready to jump on a Zoom call with someone you’ve never met before to help walk them through an issue. It might be intimidating at first to interact with people you don’t know, but you have to do it if you want to grow. This is a sure way to meet new people and make new friends that might be helpful to you in the future.

Having some sort of contribution guidelines with all the information they need to make their first contribution is critical. Making that first pull request should be as frictionless as possible because they’re more likely to stay if things go smoothly the first time.

Klint: Do you feel like you’ve developed a “personal brand” or personal communication style? If so, how have you cultivated it?

Aaron: I think I have a personal communication style and you could also call it a brand. I try to be kind, empathetic, sensitive, and confident. That’s how I try to show up online. When someone interacts with me, I try to be kind, even if I don’t agree with them. I think in engineering circles being kind has been sacrificed at the altar of being correct, and I think it’s a huge false dichotomy. That’s particularly important if you’re trying to get enterprise adoption or sponsorship for your project. Large organizations are not going to want to interact with people who have bad public communication hygiene or bad public personas.

Segun: I think of personal branding as what people expect of you when you step into a room. What do you want to be known for? People build a mental model in their mind of what kind of person you are based on what they see: the talks you give, how you behave on social media, and how you treat others online. I’ve picked an area of expertise—design systems, state machines, and accessibility—and I do my best to share helpful tools and ideas I learn freely with others. I think this has earned me a reputation that I intend to uphold over time. The biggest thing I try to do is to be open and vulnerable. I admit what I don’t know. I try to learn from other people’s perspectives. I think really listening to people, one-on-one if possible, helps create a positive impression.

Tasha: I don’t think I have a personal brand. I don’t think I’ve been single-minded enough about curating my Twitter content, for example. But my communication style is upfront, consistent, and transparent. When I talk to you, I will give honest feedback. The way I developed it, or at least became aware of it, is that I used to get the feeling that I needed to be less direct or up front with people. I mentioned that to an executive coach who said that rather than try to change, I should lead with that style and say: “Our value is clear, transparent communication and fast feedback.” I really responded to that. People respond well to up-front feedback when they’re expecting it, when you’re clear from the beginning that that’s what you’re going to give them, and when you’re open and comfortable with receiving it yourself.

Klint: What role does speaking at events play in promoting projects?

Aaron: I can only speak to my own experience, but I’ve found speaking at events to be pretty important. Putting yourself out there publicly is scary, but it’s how people will find out about your work. The first talk I did for Sidecar was at a meetup. There were between 80 and 100 people watching live and I thought, “This is my big break! There are 80 people watching, I’ve made it.” It didn’t make Sidecar an overnight success, but four or five more people started using it—four or five more people who could potentially spread the word to other people. Each event you do, or each podcast you do, makes it more likely you’ll be invited to another event or interview, so you can start building momentum that way.

Tasha: Let’s look at Docker as an example. People think of it as an overnight success, but it wasn’t. The company behind Docker sent evangelists to what felt like every tech meetup, worldwide, for at least two years, to tell people about Docker and why it was interesting. People underestimate the power of focused evangelism. I think speaking with people is very human, and we tend to be more willing to try technologies if we meet someone. That said, you need to think about the actual time investment for any given event and whether your talk is a good fit for the audience.

Segun: It is important, but you need to find a healthy balance between maintaining and evangelizing the project at events. Promoting at events increases your opportunities and your project’s visibility in the community. It’s one of the most effective ways to get developers interested or excited about your project. The balance to this is the timeline between shipping your project and promoting it at an event. In my mind, after you’ve shipped a release is generally a good time to do talks and podcast interviews. But if you’re in the middle of a release, maybe you should focus on that. It’s probably best to talk about your project when it’s in a stable place, not when it’s changing rapidly. I think it’s important to have a team that can help give talks as well, especially if you don’t enjoy giving talks. If you can build a team of collaborators, there will be people who are naturally excited about evangelizing the project in conferences, podcasts, and speaking publicly about it. You have to take breaks. Having a team helps give you the space to do that.

Do you have a burning question about Git, GitHub, or open source software development?

Drop your question to us on your social channel of choice using #askRMP, and it may be answered by a panel of experts in an upcoming newsletter or a future episode of The ReadME Podcast!

The ReadME Project is a GitHub platform dedicated to highlighting the best from the open source software community—the people and tech behind projects you use every day. Sign up for a monthly newsletter to receive new stories, best practices and opinions developed for The ReadME Project, as well as great listens and reads from around the community.

Written by

Klint Finley

@klintron