I’ve been in open source for 20+ years and I’ve created quite a few popular projects like PostCSS (with millions of downloads per month.) So what’s the secret? This is the guide you’ve been waiting for: how to make your open source popular, the right way. Does ”good idea” = ”popular project”? Here’s a hint: much of the open source dream is a total lie.

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

Book a 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:

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

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.

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.

Want your agent to apply all of this? We packaged the rules below into a skill: the opening block, the ordering, and the hard rule against inventing numbers your repo can’t back up. Point Claude at your README and ask it to rewrite.

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 }))

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: