How to make your open source popular

I’m Andrey Sitnik, Evil Martians’ Lead Frontend Developer, and today I’m flashing back to my start in open source. Things were quite different when I first jumped in. To demonstrate, at that time, my initial open source projects weren’t even on GitHub! Instead, they were on SourceForge! I started 4 years before GitHub was even created.

In any case, I found SourceForge inadequate. So, when GitHub finally came on the scene a few years later, I was one of the first to hop onboard, and (humblebrag here) this is how I was able to score my awesome username @ai.

So, yeah, I’ve been around. And over the two decades that I’ve been in the world of open source, I’ve had my share of successes. While some of my projects overlap in terms of focus, there is also a lot of diversity, so I feel confident that their success isn’t just some fluke.

You can do it too, and that’s why I want to share some of the experience I’ve accumulated and help you make your open source projects popular.

Irina Nazarova CEO at Evil Martians

Schedule call

But there’s something we need to talk about first…

Don’t make open source to be famous or popular

Let’s be real, if your interest in creating open source is because you want to be famous, wealthy, or the new cool developer in town—you’re probably in the wrong game.

That said, I’ll just say that there are other more effective ways to cultivate popularity. For instance, you can give talks or write articles.

Articles are a great way to make the case and share your open source projects detail, change people’s minds, and they also have the ability to gain widespread traction—as well as the potential to continue to cultivate attention over a longer period of time.

And guess what, we’ve got a guide on preparing and giving talks:

Engineering connections: a conference talk primer for humans

Engineering connections: a conference talk primer for humans

July 29, 2024

Read also

And we’ve also got a guide on writing articles:

Why should developers write? 3 reasons and 3 common blocks

Why should developers write? 3 reasons and 3 common blocks

March 20, 2024

Read also

To see a case of how open source fame and more traditional fame are not necessarily connected, let’s look at Redux and React Router. At the time of writing, they each have around 60K stars, respectively:

Despite this popularity, the current maintainer of these projects, Tim Dorr, only has about 5K followers on X. To be fair, he’s just the project maintainer, not its creator, but these are still well-known projects (so hey, maybe you should give him a follow, for some open source love!)

Don’t make open source for a good resume

There’s also something else that everyone deserves to know. The thing is, much of the open source dream …is a straight-up lie. Let me explain one reason why.

We often hear that we must be involved in open source. But we don’t hear much about why we must be involved in open source. Well, we must be involved because we must be, isn’t that just obvious by now?

So, as a result of this and other conclusions, rather than why, the conversation often centers around how to do open source, and the answer to that can be rough: “Just come up with an idea for an open source project, make it happen, it will be OK!”

This pressure to succeed in open source becomes even stronger because many feel they won’t be hirable without a solid GitHub account. That is, an account that potentially includes some healthy open source contributions, including their own projects. (But even if it’s a lovely project, if your only star is from your 👵, you might feel a bit depressed.) In any case, many people feel this way about the reasons to make open source.

Anyway, HR does ask to see open source commits, but instead of taking that approach, it’s better to contribute to big projects, fixing docs or fixing bugs in a beta version.

Contributing before you leap

This is for folks that may need to build up their confidence for what follows. Rather than setting off on your own right away, it’s much easier to make a commit to a big, established project.

For instance, a lot of Rust and React stuff have docs by their creators, but these may not be the best people to communicate how to use the things they’ve created. Yes, they know how to use it; but they didn’t have to learn it exactly like you might. Commiting to those docs could be a way to add to your resume!

• ✅ Fix docs in popular projects
• ✅ Use beta version -> fix bugs

Or, make a PR. It’s so much easier than building a project or an app!

So, all that said, if we’re really going to be involved in open source, we need to be very clear-eyed about the best reason to do so, and in my opinion, this is the bottom line: the best reason to make open source is if you want to change the world.

How to change the world with open source

Now, of course, that’s a big statement, but while your open source might be something that changes something that is a really, really big deal in the halls of history, it also might be something more like the following case: when I created PostCSS, my goal was to add more diversity to CSS tooling, created a basement and ecosystem to create tools for CSS processing more easily. And it worked!

Change accomplished! But if you want your own project to change the world at any level, popularity seems like a pretty important factor to get the ball rolling.

So what’s the secret formula for popularity, damn it?

OK, let’s make something clear: a good idea does not necessarily equate with popularity. So, with that basic truth out of the way, if you’re still following me, let’s actually look at a working formula for open source popularity:

Your popularity + promotion + benefits for users + luck = project popularity

Sadly, you may have noticed a problem right away: your own popularity and your project’s popularity has a bit of a circular relationship between .

Actually, this is why (unfortunately) we often see a lot of popular projects created by popular developers—not necessarily by better developers. (In other words, they’re just leveraging their social capital for success.)

Rather than think about the potential injustice of it all that, let’s just try to analyze things as they really are.

How people chose an open source solution

On that note, let’s now take a moment to discuss how people choose open source projects. Certainly, many would naturally think we choose tools on a rational basis. This would especially seem logical for those in the tech world Unfortunately, this is completely, obviously wrong.

Here’s a thought experiment: have you recently started a project? How did that go?

• Did you try to make a small prototype with all possible frameworks and languages?
• How many languages did you try?

This depends, but in reality, most projects are simply started by frameworks with more stars. Devs just go to GitHub, see the number of stars and choose a framework based on this, or they choose based on a framework they heard about at a conference.

Understanding how people actually read

This is also a good spot to discuss some prerequisite knowledge for what we’ll talk about in the next section: how people will actually ingest the content you create.

So, people will simply not read this stuff line by line. No way, no how. Instead, you need to think about your descriptions, documentations, and READMEs like a progressive JPEG. And actually, this effect cascades down for each level of detail, like a set of JPEG Matryoshka dolls, each of which has the potential for the reader to lose their attention. People will stop scanning at any point if they can’t find a benefit.

Because that’s how people read! So, instead, explain things first at a high level, then a more defined scale, then a more granular scale. Ease them in, (but do it quick).

Or, to understand how users often read our texts, rather than seeing this, as we’d likely wish:

Our users probably see something like this, at least at first glance.

Keep this in mind and plan accordingly.

Popularity

So, let’s move into more practical matters, and we’ll kick off with a key question: how to actually become popular? TikTok? (Maybe, if it hasn’t been banned already.) Let’s start by talking about an approach that a lot of people in the tech world often try.

Get your social media in order

First of all, make sure your social media accounts exist and are in order. Actually, this reminds me of one of my own mistakes: I originally didn’t even have an English language social account, so when people found out about my tool, people had a hard time finding the person to follow. So, if you’re a non-native speaker of English, I do recommend creating English accounts on social media!

Additionally, whenever my project was mentioned, there was no link to my profile… it just wasn’t really accessible. Now it is.

Having social media in good shape will be useful throughout all of this.

Keep a realistic mindset

Let’s skip ahead to the luck part of the formula because it seems appropriate here. If the formula “good idea = popular project” isn’t the right one, what is? Well, certainly “luck” plays a part here, but is that really the entire story?

So, get this, I have 4 popular projects. But… those aren’t my only projects. Ha, hardly.

Sometimes a picture is worth a thousand words. Take a look:

Finding a popular project can often be a marathon, not a sprint. I believe it’s appropriate to keep in mind that every project you created could be fail. But the only way to create a popular project is to do a lot of sacrifices, persist, and repeatedly try. This will help your “luck”. In fact, the proper mindset going into each project may be expecting failure, but of course, don’t let this affect the quality of your work!

How to make your open source project popular: the README

Now, let’s talk about setting yourself for success at a basic level.

So, in terms of your docs or README, it’s best to start off with a detailed, step-by-step guide on how to use your tool right? Jump right in; time is money after all. Well, well, wait, hold on just a minute there!

Your README and your documentation act as a first impression for any prospective user of your project. Really, no matter how you end up promoting your work: talks, posts, podcasts, or whatever, at the end of the day, this is where a big chunk of your potential audience will end up. So we definitely need to spend some time here.

As mentioned above, readers won’t go through your README line by line… nonetheless, they’ll still need to quickly understand the benefits that your project offers them.

Ask yourself: have you done enough to effectively demonstrate the value your project offers?

To make your project popular, people need to see the benefits immediately, ideally in the first block of your README.

Likewise, people do not cozy up by a fireplace and meticulously read our documentation line by line. The reality is the exact opposite. People don’t have time to do stuff like that, so get your documentation in order. Let’s go deeper into what that means.

1: Demonstrate benefits for users

In many ways communicating the benefits for your users is directly connected with promotion. Let’s recall our formula from before and let’s hone in on the bolded point below:

Your popularity + promotion + benefits for users + luck = project popularity

So, whether we’re talking about a README, documentation, or a blurb somewhere, in a sea of irrational choices based more on popularity than merit, how can one possibly cut through the noise and effectively demonstrate the benefits their solution offers users?

The proper answer to this question has multiple parts, and also relates to how human beings consume information (pay special attention to this point, scannability, readability, and those quick impressions are a priority).

2: Ruthlessly understand how to communicate your message quickly and effectively

So, in fact, let’s get specific. Your opening block should have three things:

1. A clear description
2. How the product is useful for users
3. The difference from other products

Start by making explicit why it’s worth reading your documentation in the first place! The most important part is the first paragraph because, well, people only have time to read the first one. This is the block where they’ll understand if your project will have benefits. So this demands extra efforts. Let’s take a look at how this work with a real example, from PostCSS:

Don’t use “tech speak,” write like you’d speak with your colleagues in real life. Here’s another case from Nano ID:

Demonstrating this value ASAP is so critically important for maximizing your success, so there’s nothing wrong with spending a lot of time on this, even up to a week.

3: Describe your product …like you actually want people to undertand what it is

Following up from that last example, let’s look at some less than ideal examples. Take Svelte. It’s an amazing framework! But let’s look how they described themselves.

It looks cool, it looks fun, sure… but does it explain why it’s better? Maybe we could give it a shot…

My advice for making a good description: simply imagine you’ve gone to the bar with your co-workers! 🍻 “Oh, you’ve written a new tool, what does it do?” Then, just explain it to them in real, human terms! From there, use this as the basis for a text description of your open source project.

Once you’ve got your little bar pitch down, get even more ruthless and cut that explanation down! 🪚 🪚 🪚 🪚 Then, cut it 2-4 more times!

4: Use lists and bold texts to help people quickly absorb info

Look at this:

Nano Stores is a tiny state manager for React, React Native, Preact, Vue, Svelte, Solid, Lit, Angular,
and vanilla JS. It uses many atomic stores and direct manipulation. It's small, between 286 and 818 bytes (minified and brotlied).
It has zero dependencies.

You get the point. Now look at this:

There’s really not much to debate about which one is easier to extract info from. But if we really wanted to analyze this, we could strip away the parts that lack the bold points and easily understand that the essential message is still communicated.

5: Use code examples and images

People often need less bandwidth to understand an effective example or illustration. A picture is worth a thousand words, after all. So use visuals.

6: Use real stats. Like, real stats.

To repeat: use real stats. People don’t put too much faith in vague promises or “concepts of stats”. This is especially important to consider if you’re trying to differentiate your product.

Instead, use a real benchmark, not some lofty language of PR promises. For example, here is how I demonstrate my claims about how “small” Nano ID is:

Likewise, we can look at the benchmarks to prove how “fast” it is:

In your case, if one of the great benefits of your open source is the API, well, then show the API:

// Redux
switch (action.type) {
  case 'INCREMENT' :
    return state + 1
  case 'DECREMENT' :
    return state - 1
  default:
    return state

// Storeon
store.on( 'INCREMENT', ({ count }) → ({ count: count + 1 3))
store.on( 'DECREMENT', ({ count }) → ({ count: count - 1 }))

7: Finally, from there, share that step-by-step starting guide

Then, if you’ve managed to effectively, quickly, clearly communicate all the reasons why a potential user should read more about your project, they will be motivated to continue reading.

And then—and only then—do I suggest providing a step-by-step guide about how to use it.

Again, respect people’s time! In my README, I don’t just say something generic like “use PostCSS”, and instead I give very specific instructions:

And, of course, with variations in the path as needed:

If you’re up for it, you could also make separate sections for different types of users:

Then, once you’ve got all that, you’ll need to actually test it, and this is absolutely essential! One way to do this, if you can, try to wipe your memories clean about your project and follow your own guide from scratch.

Practical promotion in action

So we’ve got a good README, solid docs, your texts are in order and your head is on your shoulders. What now?

Many people make a mistake at this point. Here’s what happens:

1. They make a single social media post
2. They get nothing.
3. They get depressed.
4. They stop working.

What was their mistake? They didn’t do a “slow” promotion. In other words, it can be a big mistake to have some huge blow out launch. Instead, promote your project iteration by iteration.

Here’s what a promotional interaction should contain:

1. Content or info about some action (a feature release, social post, article, and so on)
2. Feedback
3. Fixing the project according to feedback
4. Making content about those fixes OR going for new product results (go to step 1)

Believe me, just because you’ve created your amazing project and feel ready to share your work—truthfully, it’s probably not quite there yet.

And this is why iterative promotion is so important!

As you explain your work, you get feedback thus allowing you to improve your project. Further, it’s even a GOOD thing that the first iterations of your project are likely to have a lower number of users: this gives you a less stressful atmosphere to correct those issues.

Then, as you continue to iterate, you can change it up. The next iteration can include:

1. Something even bigger you’ve carried out
2. More feedback
3. More things to fix

Effective promotion with social media posts and articles

When writing their open source social posts, a lot of people just insert a link or include some cryptic explanation. So, if that isn’t enough, then how to write a good post?

Let’s get practical:

1. Put a code example or image; people like them and they’re easier to process.
2. Put a clear product description. Even if you’re talking about a new feature, explain the project from scratch because it might be their first time seeing it.

Let’s take a look at what I consider to be a pretty solid template for a post I did announcing a big update for Size Limit:

Share this on all the social media of your choice (at the time of this writing Bluesky is still having a moment, but all the familiar culprits are lingering out there, too).

Then, go to Reddit and post. Try to find the particular subreddit that will be receptive to your post, and pay attention to the individual rules of each subreddit. It may take a little work but finding your community can be a worthy investment.

Hacker News can be tougher to gain traction on, but has a huge readership and we highly recommend reading it anyway.

Then try to write a full article about it! Publications like Dev.to, Smashing Magazine, and CSS-Tricks can be open to submissions, and at times their editors can also give guidance. Reach out and give it a shot!

Promotion via PRs!

And now here’s the FUN part… don’t be afraid to approach other projects with a PR featuring your library. (In fact, this is how PostCSS was promoted!) Think about it: if you’ve created a good library, you’re HELPING other people, you’re not “boring” them, you’re doing something good.

And here’s another thing, if they actually apply the PR—use their names in your README! People respect big names, and it just feels good for everyone anyway!

What’s next? Iterate, iterate, but DO NOT SPAM

From here, it’s time to iterate on it all.

1. Refining your code, README, and texts
2. Making announcements
3. Writing blog posts/doing talks
4. Getting feedback
5. Improving your project based on the feedback

But please, in the process of doing this: do not spam! Post regularly. But never spam. There is a difference. Deliver value, don’t post the same messages, tell the continuing story.

It’s also important to develop a regular habit because people do not read every social media post. So, say you’ve explained this amazing post that encompasses everything about the idea of your tool… I mean, a story that could melt hearts and bring tears to developer eyes…

Could happen!

Or maybe your client had some wine that evening and kind of just glazed over your masterwork. This is why posting regularly is so important!

Remember, we’re back to the question of choice. Do people choose rationally or irrationally? Regular posting is important because it is your way of slashing through the dense forests of irrationality.

Bonus: Oh, s**t, I’m actually popular. What am I supposed to do now!?

Congratulations, you’ve made it. 🤝

Your dedication and adherence to common sense practices has finally paid off and you’ve got a popular, successful open source project on your hand.

But now another problem arises… you’re popular! And… there are issues with come with that. Literally, issues can start to build up. So many, in fact, that you may start to feel you are a bad maintainer. This can cause depression, and this can cause a lack of productivity.

What to do?

First of all, don’t do everything for your issue reporters. This is open source! It’s not about having a maintainer as a free worker. So, if a user wants something… they can do it, and you should encourage them to do so: simply ask, “can you send a PR”?

Then try to spend set time everyday, say 15 minutes, to deal with the issues. If you encounter a hard issue, it’s OK to simply acknowledge them. In fact, it’s good to say: hey, I see you. Even if you can’t give the solution, this is a solution—people sometimes just need to be heard, and this is meaningful too.

As another open source maintainer idea, you can also ask users to change the documentation, too.

Bonus 2: Dealing with negative feedback

How to deal with negative feedback? What if some people hate your tool? Negative feedback can happen at any part during the process. And it can have disappointing consequences no matter the time: when you’re starting out, it can be a real kick to your sense of motivation. If you’ve gotten more popular, it can raise insecurity and doubt.

Take a look at this less than stellar feedback:

Well, first of all, damn, that was tough. Negative feedback can really hurt your soul, let’s just say it!

But we can try something anyway: you can start to ask questions and engage with your critics: why do you think B is better than A?

You see, sometimes haters aren’t actually haters. Rather, they just want to vent their pain, and who better to listen than you? So don’t be afraid to be there for them!

Bonus 3: A final note on open source “competitors”

So you’re popular and competing projects begin to pop up. Bottom line: don’t be afraid of competitors.

Because 1: you can finally stop supporting your project, and 2: we’ll have an even better solution changing the world with the same (or similar) vision! Talk about a win-win for everyone! 😊

After all, like I said at the outset of this article, the best reason to get into open source is to change the world, not to monopolize or remain the only game in town.

Let’s recap

Making popular open source and understanding visibility

1. The best reason to make open source is to change the world, not for fame or padding a CV.
2. Crucially, “good idea” does not equal “popular project”.
3. Popularity is important for successful open source, and the formula for your project popularity is project popularity = your popularity + promotion + benefits for users + luck.
4. Your social accounts should be active, findable, and casting a wide linguistic net (e.g. English language).

Documentation best practices

1. Your documentation and README should be clear and natural, as if explaining things to friends at a bar.
2. Use bold text, lists, and proper organization to progressively unveil complex info as users dig deeeper.
3. Share “real” proof. Actual benchmarks that matter, and code examples that demonstrate value.
4. Provide specific getting-starting guides, tailored to different cases, if possible.

Promoting yourself

1. Don’t just do one big launch; promote iteratively: release → get feedback → improve → repeat
2. Post regularly (but don’t spam!)
3. Use code examples and images in social posts.
4. Submit PRs to other projects using your library!

Tips for when you’re already popular!

1. Don’t try to do everything yourself, encourage users to submit PRs.
2. Set aside specific time for issues (e.g., 15 mins daily).
3. Ask questions if you see negative feedback.
4. Don’t fear competitors-they can free you from your open source responsibilities! 😉