Open Source visibility hacks — No icky marketing needed

Hundreds of engineers put their projects on GitHub, yet, for whatever reason, many potential users simply cannot find these projects. Open Source authors often possess top-notch coding skills, but user outreach can be a challenge. Perhaps they just don’t want to mess with any of the “marketing” stuff that has a bad reputation in the Open Source community. Or, they’re just introverts.

I work in a company called Evil Martians with 100+ OSS projects and my job is to help their creators make these projects accessible to users.

Forget chasing people down or diving headfirst into marketing – introverts rejoice! There are five practical steps you can take to move your project forward, all without needing my specific skillset.

You need users; users need you

Whatever your reason for building Open Source (whether it be pumping up your skills, solving a problem you can’t shake, contributing to something great and promising, or for GitHub stars), you need users. 

Without users, we just can’t improve our projects because we live in our own problem space, which is likely to be very limited. The product we’re building may apply to many situations.

Yet, in practice, developers don’t mindlessly scroll through GitHub to find a useful project. Instead, they search, follow interesting engineering people on social media, subscribe to newsletters, or attend conferences.

So, keeping this in mind, let’s outline some steps to help users find you and put you into circulation.

Step one: Get your README in order

Many projects have empty descriptions and threadbare texts. However, the description is most critical—it allows readers to understand what a tool does and motivates them to use it. 

Here’s the best README structure:

1. A clear description
2. How it’s useful
3. Why it’s important
4. How it differs from other solutions

You can find some inspiration for shaping the content in your READMEs by references to our own Open Source products: Nano ID and Autoprefixer. 

The README is so important, but it’s also the most difficult content to create—sometimes, it can take weeks to properly and thoroughly produce. 

I suggest using this technique: Tell your friends (or, in the case of introverts, AI tools, or yourself) about your project idea—you can even go so far as to record and transcribe your speech. During this process, try to explain your idea as clearly and simply as you can.

If, after that, you still can’t formulate your content, then it’s probably because you’re trying to create a type of marketing text that’s beautifully wrapped up with “selling” words. This mindset makes you think formally and it’s also useless because people, again, don’t search for beautiful marketing phrases. 

Instead, use informal speech. You could even get emotional or use an angry tone, go with wording not appropriate in high society, or, in a worst-case scenario, some healthy obscenities. Whatever you do, try to go beyond the limits of a “beautiful” text that will sell your product and, instead, think like the people who will be searching for the same solution you had to solve.

Forget fancy marketing speak. People search for solutions, not beautifully wrapped ‘selling’ words.

After you’ve gotten everything out there, you can get rid of the most unpleasant terms and rewrite the entire text, making it more professional. Write several different iterations and test them with your users.

To top things off, add a prompt and method for getting feedback, like “If you found this documentation vague or not clear enough, please, submit an issue or a PR. Let’s make it better together!”

Step two: Make it appealing

Let’s next set our eye on making our README files more eye-catching.

Many researchers report that people don’t actually “read” things online (instead, they scan texts, rather than reading them word for word.) For instance, research by the Nielsen Norman group, which included data gathered via eye tracking, demonstrates that readers pay most of their attention to the beginning segment and any featured details.

So, allow your readers to easily scan and find the most important information for them. READMEs with eye-catching details like lists and bold type can highlight key points and the use of images (screenshots, logos, diagrams—since GitHub added Mermaid support recently, it’s quite easy) can be a good idea, too. To create beautiful code snippets, you can use a nice Open Source monospace font like Martian Mono, FiraCode, Iosevka, or Monaspace.

Step three: Get rid of any red flags

When developers search for solutions to their problems, they don’t type something like: “I want to find an unprecedented and innovative solution for deployment automation.” They use concrete terms and these concrete terms should exist across all forms of your content.

In particular, stop using buzzwords—because these are red flags for potential users.

I bet you have your own list of IT buzzwords that you hate the most, like “blazing-fast,” “rockstar,” or “ecosystem.” (For the record, mine is “innovative.”) However, if search for words like this on GitHub, you’ll be overwhelmed. For instance, you’ll see Open Source project descriptions including “innovative” numbering at 19.7K and over 5.1K of “blazing-fast.”

If your product is the “fastest,” “smallest,” or simply better than others—provide proof, like benchmarks and statistics.

We made this mistake by using “blazing-fast” for our Open Source image optimization project, imgproxy. Thankfully, we soon realized our error and removed it from our README, providing benchmark results instead.

Step four: Be consistent

With the README out of the way, you’re poised to make a great contribution to the community. But to keep the visibility and searchability, keep in mind it’s a marathon, not a sprint. So, this means we should prepare to regularly generate our content.

This hits two targets. First, it shows that your project isn’t dead, issues will be promptly dealt with, and users will get new features (abandoned OSS projects are a huge problem.) Second, fresh content signals activity to search engines, potentially boosting your product’s ranking.

Another point on that last note: when people search for a solution to their problem online, they use different combinations of keywords. That’s why we need to constantly use different phrasing.

So, reuse and repurpose your content. Create a good README and turn it into a blog post. Write a guide on how to use your project (they work very well!) and transform it into a social thread, Reddit post, and, again, a blog post. Announce releases and new features, thank contributors, define use cases, share big fixes, and post benchmarks.

For instance, for one of our OSS projects, AnyCable, we’re constantly reusing our content and transforming it into screencast episodes, newsletter issues, or Twitter and blog posts to continuously engage with our users.

Step five: Find more content ideas

Having trouble finding content ideas? Write about a problem that annoyed you so much that you decided to create your own tool to solve it. Or write a tutorial to show how to use your features or a use case for a particular tech stack. Think about the problems you faced during development. Or, consider solutions you tested but didn’t fit.

And try to glean inspiration even from negative feedback: Share the stories about your issues and how you solved them (or failed to do so!).

In general, we need places to connect with users, and the more content and channels we activate, the greater the effect. And be sure to listen to your users and contributors—they’ll help you find the idea for your next piece of content.

Remember: Promotion in the development world is really about peer support, a win-win for all. People work with our Open Source, create issues and send pull requests. Collectively, by discussing use cases, solving non-trivial problems and looking at other people’s code, we contribute to something more.

This approach steers clear of ‘ick marketing,’ the inauthentic and pushy tactics that turn people off. We’re all sick of the overhyped features with no real value, exaggerated claims with no data to back them up, or overly promotional content that drowns out genuine value. A good description and documentation, the ease of finding it, and regular content are signs of a decent quality OSS project.

This article is part of our series on Practical Open Source (POSI) program. POSI aims to facilitate discussions about doing business with and for Open Source. The 2024 edition consists of blog posts on OpenSource.net and a panel at All Things Open in October. More details and how to pitch on the POSI 2024 page.