TL;DR README of your repository should show/present your code as if it was a product that you sell.

Disclaimer: it is my personal blog. What I describe here works(ed) for me. There is no guarantee that my approach is an ultimate guide that guarantees a 100% result. Also, trying to get N GitHub stars itself is a bad approach — I just want to help you understand how to make other people notice the work you have done already.


6 months ago when I and my friend were preparing to launch a closed beta of NewsCatcherAPI I had a simple idea: Why don’t we open source some of our code? At this point, my only motivation was to get more sign-ups for our beta.

A few days later, I released my first Python package with a GitHub public repository. It was a simple Python package that collects normalized news from (almost) any website. One function that takes any news website’s URL as an input and returns the latest news from it.

Soon, I will write about how to easily make Python packages via Poetry. So, subscribe not to miss. It’s free.

Within a matter of a day, we had 300+ stars on GitHub. That seemed like a miracle to me! If I had 100 stars I would consider it a great success. It was just a 50 lines code with an SQLite database with 3,000 rows in it.

Today, after the release of version 0.2.0 we have over 2.2k stars.

Later on, I open-sourced 2 more repositories and they also got lots of stars (attention from the community). But, more importantly, unlike my first repository which was somewhat unique, similar repositories already existed for years without stars.

In this post, I first explain how I make my repositories get noticed. Then, I will compare my Google News Python wrapper that got 500 stars over the first day being published with other similar projects with just 29 and 16 stars.

Your repository is your product

Over the past year, I began learning about how to make my own product. YCombinator’s Startup School helped a lot.

3 core things I learned:

  1. Make a one-liner that describes your product. It has to catch attention in 5 seconds max

  2. Do not use slang, and assume your audience does not understand anything of what you did

  3. Show the value!

I applied the same approach to my GitHub repository. And, I think it is the major factor of it being noticed.

Yes, without code there is nothing to show, however, how many people will be willing to dig into your code to figure out what is it doing?

One-liner to describe what it is

When you create a new repository on GitHub you are asked to fill in a Description. That is a place for your one-liner. It is just one or two phrases to describe what your repository is all about.

In most cases, it is not possible to fit in all the features and functionalities. So, here is my advice — describe the most valuable thing.

Also, make it specific.

Know your audience

Who is this repository for? Do these people know it might be a good fit for them? Leave a few use-cases and examples to help them understand.

Good examples might induce people to new ideas.

Assume your users are newbies

The majority of people into coding are first-year/month coders (in my opinion). They do not have a broad understanding of Computer Science (CS) as you might have.

For my first 2-3 years into coding, I could not understand 80% of GitHub projects I saw: the authors always assumed that I already have a decent background.

There are plenty of people learning code without a CS degree!

Plus, even non-CS degrees at universities have some coding classes nowadays. Journalists, economists, mathematicians, chemistry, physics — all students are taught some basics of coding. Whomever. Everyone learns Python nowadays.

Better to see something once than to hear about it a thousand times.

If you go back to the gif where I quickly go through 3 of my repositories you will see one similarity — all of them begin with a DEMO.

People are either busy or lazy. Either way, they do not want to read. So, use it as your advantage — record a demo.

People will give you a star just for the knowledge that such a thing exists.

500 stars VS 29 stars

Within one day, my pygooglenews package for advanced Google News data mining got over 500 stars. It has a GIF demo of what you could achieve with it, explains what it does, and provide a set of use cases. When you open it, you realize what YOU can use it for withing seconds.

While working on this package, I had to collect lots of information about Google News because there is no official documentation. So, I also checked if there are some Python packages that do something like that already.

To my surprise, there was a package that does the basic stuff. It is not as advanced as the one I did but still many people may want to use it. There was another one that did even more. They had 29 and 16 stars respectively. Why? I think it is because both times I had to dig into the code to figure out what they are all about.

The lesson here is that thousands of people actually could use the code from the other 2 repositories. But they could not understand what those repositories are about.

To sum it up…

  1. Assume that people that will open your repository are coding for 1 day

  2. You have just a few seconds to get them involved. One-liner. Make a demo

  3. How to make your code work. Installation guide. Examples

  4. Promote it: Reddit, HackerNews, etc

Get 80% off for 1 year

Other reads that you might find interesting:

  1. Write clear READMEs to increase your chances to find your first coding job

  2. One simple yet crucial thing I learned from YC’s StartupSchool

  3. “Reverse Engineering” Google News RSS Feed. Part I.

Source link