How to promote an open-source project

There is an asymmetry that catches almost everyone. You have spent months with the problem, so the value of your project is obvious to you. To everyone else it is one of forty repositories they will glance at this month, and they are not reading. They are scanning for a reason to eliminate it, because elimination is faster than evaluation.

GitHub does not solve this. It is excellent hosting with a social veneer, but nobody browses it hoping to find your library. Discovery there is almost entirely downstream of something that happened somewhere else: a link in a newsletter, a comment in a thread, a colleague’s recommendation. Publishing a repository makes a project available. It does not make it findable.

The single most common mistake is doing step four first. Driving five hundred people to a README that does not explain what the thing is does not get you five hundred evaluations. It gets you five hundred people who now believe they have already assessed your project and passed. You cannot re-launch to the same audience. Attention spent against a broken first screen is worse than attention not spent, because it converts a future prospect into someone who thinks they have seen it.

So: fix the documentation before you buy the traffic, even when the traffic is free.

“Developers” is not an audience. Neither is “people who need caching”. A usable answer names three things:

• The person. Not a job title but a situation. “Someone running a Python agent in production who cannot tell which tool call is slow.”
• What they do today. Every project competes with an alternative, and the most common alternative is a pile of print statements and tolerating the problem. If you cannot name what they currently do, you cannot explain what you replace.
• Why they would switch. Not why your approach is better in principle. Why it is worth the twenty minutes of changing something that already sort of works.

This is unglamorous and it determines everything downstream. The README, the venues, the words you use in a thread: all of it is derived from this answer, which is why getting it wrong is expensive and getting it vague is worse.

Whatever sits above the fold of your README is what most people will ever read of your documentation. It has to answer what this is, who it is for, and what it looks like to use, before a reader has decided to keep reading.

The failure modes are consistent: opening with how the project came to exist rather than what it does, a feature list before a one-line description, an install command before any reason to install, and badges where a sentence should be.

We wrote the longer treatment of this separately: what a README has to do in its first ten seconds, including how to assess your own.

“Post on Reddit” is not a plan. The plan is a specific subreddit, a specific Discord, a specific newsletter that already has the attention of the person you named in step one. Three questions decide whether a venue is worth your time:

• Are your users actually there? A large general programming community is usually worse than a small specific one. Ten thousand people who will never need a tracer are worth less than two hundred who are debugging agents this week.
• Does it permit this? Read the rules, and read the last fortnight of posts. Some communities welcome project posts in a dedicated thread and nowhere else. Getting this wrong costs you the venue permanently.
• What is the local form? Show HN, a subreddit’s self-promotion thread, and a Discord’s showcase channel all expect different things. The same text pasted into all three reads as broadcast, and broadcast is what people filter out.

The useful test: if you deleted the link, would the post still be worth reading? A post that explains a problem you hit, a decision you made, or a benchmark that surprised you earns attention on its own, and the project is the credible answer to “how do you know that?”. A post whose content is “I made a thing, here it is” needs the reader to already care.

This is also why the specific implementation detail usually outperforms the feature list. People argue about how you handled concurrency. Nobody argues about your bullet points.

Most projects launch once and then go quiet, which means the entire distribution strategy is a single day that either worked or did not. Projects that grow have something to say every few weeks, and the cheapest source of that is work you are already doing: a release, a meaningful fix, a thing you learned while building.

None of this requires you to become a content marketer. It requires the output of the work you already do to leave the repository.

Stars are the easiest number to see and among the least useful. They tell you that people encountered your project and reacted, which is a distribution signal, not an adoption one. A project can gain two thousand stars from one good thread and have four users.

Track the things that indicate someone is actually trying it: package downloads from real installs, documentation visits that go past the first page, issues that read like usage rather than drive-by questions. We go into what stars do and do not tell you, and what to watch instead.

None of the six steps is difficult. The problem is that they are ongoing, and they are a different job from the one you wanted to do. Positioning drifts as the project changes. A README written at v0.2 is wrong by v0.9. The communities move. The release you shipped on Tuesday is the thing you should have written about on Wednesday, and by Friday it is stale.

Most maintainers do this in bursts: a good week after a launch, then nothing for three months. That is not a discipline failure; it is what happens when the work has no home and competes directly with shipping.

Orviqa is built for exactly that gap. It reads your repository (the source, not just the README) and turns the sequence above into something that persists between the weeks you have time for it:

• Audience and positioning derived from what the code actually does, so step one is written down rather than carried in your head.
• A README audit that names what is missing and what to change, classified by how much it costs you.
• Named communities where that audience already is, with a draft for each in the form that venue expects.
• A 30-day plan that starts with fixing the docs rather than with posting, for the reason in the section above.
• Release detection, so shipping something is what prompts the writing rather than remembering to.

Two things it deliberately does not do. It does not post anything without you approving the specific draft. Nothing is scheduled and nothing goes out automatically. And where a number is needed that does not exist, you get a placeholder and a list of claims to verify rather than an invented figure.