by TOAST UI
What I learned from an old GitHub project that won 3,000 Stars in a Week
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.
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.
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.
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.
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.
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.
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.
Visitor Incentives from GitHub Trending
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.
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.
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.
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.
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.
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.
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.
In addition, the number of stars needed to be listed on top varies significantly depending on the topics.
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
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.
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.
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 ?