How To Present/Showcase Open-Source Projects [Practical Guide]

How To Present/Showcase Open-Source Projects [Practical Guide]

TL;DR Treat your open-source project as your product to sell


Notice: 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.


demo github repo


In the end, I will compare two almost identical Python projects that do almost the same. One with 1,000 stars, and another one with 100 stars.


Why would my repo need GitHub stars?

More GitHub stars --> more exposure --> more feedback

If you open-source something then I assume you want others to profit from your work.


How to Present your Repository

Treat your repository as your product that you have to "sell". You sell it for someone's time.

For example, let's take the YCombinator’s Startup School approach:

  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!

Apply the same approach to your GitHub repository.


One Liner

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

The majority of people into coding are first-year/month coders. 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.

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.


DEMO. Just Show What Your Code Does

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.


1,000 stars VS 100 stars

Within one day, my pygooglenews package for advanced Google News data mining got over 500 stars. It has:

  • GIF demo of what you could achieve with it
  • explanation of what it does
  • set of use cases

When you open it, you realize what YOU can use it for within 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 120 and 20 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.

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

  • Assume that people that will open your repository are coding for 1 day
  • You have just a few seconds to get them involved. One-liner. Make a demo
  • How to make your code work. Installation guide. Examples
  • Promote it: Reddit, HackerNews, etc
  • By using this website you agree to our Policy.