by TOAST UI

What I learned from an old GitHub project that won 3,000 Stars in a Week

SEdkr9OFX5pHVY-WKS7hCm5w7YiGHKBCRtul
Hooray! 5,000 Stars!

A Lonely Open Source

We have been developing a Markdown WYSIWYG Editor project for three years, with its first commit in March 2015. I went to work on December 30, 2017 to release version 1.0 and publish it to npm.

At that time, the repository was as quiet as the air in the office at the end of the year. An issue posted once in several months, and it seemed to try to say “This project is open source.” It received exactly 160 GitHub stars over three years, and a pull request was hard to expect.

No surprise. Even from Google and Facebook, there are open source projects that have no contributors. I guess some of you may have experienced disappointment as your precious open source went to nothing but the void. Moreover, we are used to using GitHub as our free Git repository. Aren’t we?

As of release 1.0, I wanted more people to know about this project. I believed this project was worth more than what it looked like at that point. I did a few things to accomplish that, and as a result it got 2,000 stars in 4 days and 3,000 stars in a week! Now It has over 5,500 stars and full issues and pull requests. It happened in only one month.

fxEd5o4o2pUlorTc9inK0ShqcPRAeKbbbdIc
Yes. I tried to record everything that seemed important. ?

I wrote this article to share my experience over the last month. I will also show you the numbers I recorded when possible. I hope it can help you to make your open source project full of contributors.

A good README file earns stars

Despite the nearly three years we had been developing our editor, no one seemed interested in it. It was inevitable, as the documents were poor.

Even for a washing machine, you will want to read the manual once. You should provide even more documents for your project.

The README file describes the essence of the project. The DEMO shows it is ready to use. Examples should be the first step in various requirements. Tutorials should help anyone get started.

If you miss any of these documents, users will give up on your project. Pushing out source code doesn’t make your project an open source project.

Among the documents, the README plays the most important role. It is not enough just to list several documents. You, I, and most developers are lazy. Most visitors will simply scroll down about twice on the README and leave if they are not interested. So, the README file should provide the reason why developers want your project.

VN2sBeV4QJppueU7fffqSQKqaMausO9oEKBU
TOAST UI Editor README.md for 0.14.0 and 1.0.0

Let’s see what difference updating the README file brought. GitHub Stars are actually nothing but bookmarks for visitors. But the number of GitHub stars tells you how much visitors are interested in your project.

The tables below are the number of stars and unique visitors I recorded before and after I published the TOAST UI Editor 1.0.

There were no features added or design refreshes. There were only updates to the documents — mostly in the README file — and some refactoring. The following numbers resulted entirely from changes in the README file.

T4viYEoUzOI5wh9T1yLa7R5jQqcvHdKwTyji
Number of Unique Visitors and Stars. Documents update on 12/30/2017
GaCXGWvuhf95YHVXrVFPp14YYvmZbBAOcbSR
Star/UV is almost 5x after updating README

It would’ve been better if we had a record from the start of the project. But I just recorded the numbers to check on trends. I can’t help this at this point. So, let’s just look at the numbers, and I’ll leave it to your gut feeling.

Before updating the README file, about 4% of all visitors gave a star. Surprisingly, after updating the README file, about 20% of all visitors gave a star. By updating the README file, this project received almost five times more stars from visitors!

Everyone says that the README file is important. But who knew it would make such a huge difference? I was also surprised to see this. If you want to have contributors on a project, you should write a nice attractive README file more than anything else.

You can easily find articles about how to write a nice README file on Google. It is also a good idea to study the READMEs in other projects listed on Awesome Readme.

Spread the word around the community

Our project had about ten visitors a day. If you worked hard on your documents, it is time to let people know about your project.

Of course, it would be best if someone else spread the word about your project instead of you. But you have to start it yourself. If your project is not linked from anywhere, it won’t be shown in Google searches. Nobody would know that your project exists.

Talk about your project every chance you have

Answer the questions on StackOverflow and Quora. Talk to people in Facebook Groups. Submit a link to HackerNews and Reddit. And ask Newsletters to post your project.

CBGMjGs-i9eacEIZ8xKdCLs33H2rMdiez5YB
Tell them what your project is.

You can also ask communities to help you with your project, as well as tell them about your project.

But, do not spam them blindly. Communities and the media have different personalities. Spamming your project without understanding each community may cause your posting to be deleted or simply ignored. In the worst case, you may be banned from those communities, or your project may get a bad reputation.

Be active in each community to understand them. Knowing communities is not just good for PR. What you learn from them will help your projects, too.

One day a salesman told me:

“Engaging your customers in your work is the best way to get loyal customers.”

I agree one hundred percent on this. And I think we should do the same for our work.

As I updated the README file, I asked them to review the document. And thankfully, two people sent a pull request after reviewing the new README. I’m sure the two of them are more interested in our project than any other visitors. I bet they also hit a star on our project.

2ZzKAhZ8Rkt6E30BX8wLuAqjrRS3DntIOwC2
Thank you guys ?

Learn GitHub Explore

GitHub is the best place to get your contributors. If your project is on GitHub, don’t look too far away, and learn more about it first. At the top of GitHub, you can always find a menu that follows you around with a cute Octocat. The Explore is what we should pay attention to. The page shows developers useful and interesting open-source projects.

Explore gives you an opportunity to showcase your project to 24 million GitHub users. That’s why you should maintain your open source project on GitHub.

Other services are also great, so don’t get me wrong. I have been using BitBucket for a very long time to manage personal projects privately. GitLab also has really nice features that sometimes work better for me than GitHub’s in recent years. However, open source projects must be maintained on GitHub to get visitors from Explore.

uKJBu0akQT8hAe-QGY9CiF6HV1zP34Ud1P5O
GitHub Explore Trending & Topics

Take a look at what kind of project there are, discover what are the good parts of those projects, and how the current trend is going. If you haven’t seen the Explore page yet, it’s time to check it out. Here you can learn what you need to do to make your project better.

When you open this page, you will see the Collections, Topics, and Trending tabs — each of those list nice open source projects. Among them, we will look into Trending and Topics. We can’t help with the Collections, as it is curated by GitHub.

The Trending section in the Explore Main page shows projects that received the highest number of stars that week in all languages. Getting up there would be really hard.

v6YScBoXtOlnjtj8VIqkaKSKs43RaazIX2ak
Trending Main 1st with 4,761 stars this week. You’ll need luck to take this place.

But you don’t have to give up. Narrow the language and date range, then look at the projects in the lower ranks. There will be a realistic number which your project can also reach.

n4GCid-4SZ89d9Q9Mvs5T8Z5kT-El1Tp36XP
Trending Today JavaScript 25th with 63 stars today. You can do this too.

Focus on visitors within certain days to get on the list by bringing in every community you are in. If you can collect enough stars, your project can be on the Trending list, too. The number of stars you get depends on your project language, day of week, and so on.

If you released a new project or added features to the project, it is the perfect time to put it out there. Don’t be disappointed even if your project is listed low. Your project will still get additional visitors. Think of the Trending section as incentive for visitors based on your rank.

xgjJzmJuEXJ0zEXIAAvJnpPkFePhQ2Ki2VoG
Unique Visitors on Jan. 10, Jan. 11

The chart above is a breakdown of visitors at GitHub Insight after I spread the word in various communities on January 10. Referring Sites in GitHub Insight gives values from a two week period, so you need to make some calculations to get the numbers you want.

On January 10 — Day One — almost all visitors came from my own communities. Luckily, a small GitHub.com part in the chart shows that our editor was on the Trending list. The next day, on January 11, GitHub was already bringing in half the traffic. It is good incentive to be on the Trending list.

gSlAVbCTOm94GAUSM2uUt9fOGvpEuI7Ig5Yo
Unique Visitors on Jan. 12.

The next day, on January 12, the editor was recorded as the #1 Trending Today in all languages. Most of the visitors came from GitHub. From this day on, visitors coming in from the posts I wrote myself decreased considerably. On the other hand, as visibility increased, visitors were appearing from unexpected referrers.

Fkh7LnVBf-xxiw07DBLx0f0k-kvnxept2yMr
Unique Visitors on Jan. 13.

The following day, January 13, most visitors came from GitHub. The editor recorded 2,000 stars on this day, four days after it was posted on the communities. Although the growth has decreased since then, a month later, the Trending for This Month is still bringing in new visitors.

Steady visitors from GitHub Topics

Topics show projects in the order of the number of stars in a topic.

This means once your project has enough stars to be listed on a Topic, it can still get visitors through the Topic, even if your project is unlisted from Trending.

There are not as many visitors from the Topic list as from Trending. But it is still worth it.

-pGKqUjYfdTv3sQAsvGz8S2yi4qA5UPpF-op
Project Topics in Repository Page

I saw many projects that have no Topics. Look at the image above to see where you can set up Topics in your project. You can set up any Topics you want.

However, GitHub manages a list named Featured Topics. Therefore, it is better to choose the relevant topics from the Featured Topics to get more visitors.

85HgGTwD9TESI-T21bArImtsKG6f4-zc4DS3
GitHub Explore All Featured Topics & Popular Topics

In addition, the number of stars needed to be listed on top varies significantly depending on the topics.

Take the JavaScript Topic as an example. There is dinosaur-sized project like FreeCodeCamp (hello guys ?), BootStrap, React, Vue and so on. This makes it about 100 times harder to get your project on this list.

9hgwX85q-YLQbcHAO3sDmEH6JOgBe7tgm4XX
GitHub Explore JavaScript Topic. Your project will never beat freeCodeCamp. ?

Our editor is ranked 10th in the Markdown Topic with 5.4k stars. Take a look at the Topics and choose topics those are not too competitive.

The best single line for your project description

3RufjyexWtRQbUFwJE6z2pVVvHWHIXB99FDY
Project Description in Repository Page

Let’s find the description in the image above again. What is the project description for your project? I had written the description of our editor as a long version of the title (this is a bad idea). Have you come up with your line? Then let’s look at the next image.

fN0S0mRMAk9ZnuJKr2YdiPiP4XTToB-9ILH3
A Project on Trending & Topics List

This is what the our project looks like on Trending and Topics. Try to look at it from the point of view of visitors. There is an organization, a name, contributor pictures, and so on. The only useful information there to determine whether to click or not is the description.

The description should be the best single line to describe your project.

Final word

Write documents. Be active in communities. Utilize GitHub’s tools.

The tips I share in this article will help you make your project better as an open source (in addition to getting more stars).

But those tips alone can’t make your project popular without the value of your project itself. I hope this article helps you to find the contributors your project deserves.

I’ve had the chance to write this article because the former maintainers (Shiren, JungHwan) who did a great job for this project. I believe this project already had the value that it has today. And the tips in this article helped us achieve the rest.

Last month I had a truly special experience as a developer. I would like to thank the TOAST UI family and the Dooray! Team for all your support!

If you are interested in the TOAST UI Editor, I recommend that you try Dooray! too. It comes with the editor and is free for less than 100 collaborators. Let the TOAST UI Editor be with you ?

Pleasure to work together, Dooray!
Mail, Issue tracker, and Chat, anyone can easily post their task and collaborate with guests as well as project members.dooray.comnhnent/tui.editor
tui.editor — ?? Markdown WYSIWYG Editor. GFM Standard + Chart & UML Extensible.github.com

Originally posted at Toast Meetup written by KyuWoo Choi ?