The Old GitHub Project Won 3,000 Stars A Week
# A Lonely Open Source
The TOAST UI Editor is one of the TOAST UI Components we're working on. It has been around 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 of the office at the end of the year. An issue posted once in several months, It seemed to try to say "This project is open source.". It received exactly 160 GitHub stars for three years, and PR was hard to expect.
No surprise. Even from Google and Facebook, there are open source projects having no contributors. I guess some of you may have experienced disappointing as your precious open source went to nothing but void. Moreover, we are used to using GitHub as our free git repository. Aren't we?
Now It has over 5,000 stars with nice contributors. I wrote this article to share my experience of last month. I will also show you the numbers I recorded if possible. I hope it can help you to make your open source project full of contributors.
# Dooray! Beginning of The TOAST UI Editor
Let me start with a story about Dooray! the beginning of the TOAST UI Editor. Dooray! is a set of project management tools provided by NHN Cloud, my company. You know, the text editor is important in the user experience of the tools.
We had special requirements for the editor. Markdown mode for writing document productively that is familiar to developers, and WYSIWYG mode for collaboration with people not familiar with Markdown was needed. In addition to those, There were requirements for the mergeable cell table, code block UML & chart and etc. Of course, there were already many great editors. But none of those meet our requirements. It was the beginning of the TOAST UI Editor - Extensible Markdown WYSIWYG Editor.
If you get interested in TOAST UI Editor while reading this article, then you will want to look around Dooray! too. I bet you like it as well. :)
# No Documents, No Open Source
The TOAST UI Editor that we started developing was soon being used for the other in-house services, so we kept improving it into a separated project. As we have continued to develop TOAST UI Editor, it has become more open-source-ish.
However, despite nearly three years, we had been developing the editor, there were only a few issues or PRs. It was inevitable as the documents were poor (still not enough). No wonder nobody was interested. There was always a feature roadmap to be done and tons of bugs to be fixed. Writing documents had always been low on the list. Just a few simple tutorials and API documents were written for developers who needed those in-house.
Pushing out source code doesn't make your project an open source
Even for a washing machine, you will want to read the manual once. You should provide even more documents for your project. README describes the essence of the project, DEMO ready to use, Examples to be the first step in various requirements, Tutorials to help start, and so on. If you miss any of the various documents, users will give up your project.
# README Earns Stars
Among the documents, README plays the most important role. It is not enough just to list several documents. You, me, every developer are lazy. Most visitors will simply scroll down about two times on README and leave if they are not interested. So, README should provide the reason why developers would want your project.
Let's see what difference updating README has 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. As there were only update to documents(mostly in the README) besides some refactoring, the following numbers can be considered entirely from changes in README.
It could be better if we have a record from the start of the project. Actually, the number was recorded to see trends personally. I can't help this. So, now let's look at the numbers. Before the updating README, about 4% of all visitors gave the star. Surprisingly, after updating the README, about 20% of the total visitors gave the star. By updating the README, this project had received almost FIVE Times more stars from visitors.
Everyone says that the README is important. But who knew it would make this 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, more than anything else. You can easily find articles about how to write a nice README on google. It is also a good idea to study the README in other projects listed on Awesome Readme.
# Spread A Word on Community
Our project had about ten visitors a day. If you worked hard on the documents, it is time to let people know your project. Of course, it would be best if someone else spread a word about your project instead of you. But you have to start it yourself. Your project is not linked from anywhere, it won't be shown in Google Search. Nobody knows if your project exists.
Every little help. Tell your project every chance you have. Answer the questions on the StackOverflow and Quora, talk to people in Facebook Group, submit a link to HackerNews and Reddit, and ask Newsletters to post your project.
But, do not spam blindly. The communities and the media have different personalities. Spamming your project without understanding them may cause your posting deleted or simply ignored. In the worst case, you may be banned from the communities or your project may get a bad reputation. Be active in the community to understand them. Knowing communities is not just for PR. What you learn from them will help your projects too.
Engaging your customers in your work is the best way to get loyal customers.
One day a salesman told me. I agree one hundred percent on this. And I think we should do the same for our work. You can also ask the communities to help you with your project, as well as tell them your project.
As I updated the README, I asked them to review the document. And thankfully, two sent a PR after reviewing the README. I'm sure the two of them are more interested in our project than any other visitors.
# 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-sources.
The Explore gives you an opportunity to showcase your project to 24 million GitHub users. That's why you should maintain your open source project to GitHub instead of elsewhere(GitLab, BitBucket, etc). 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 has really nice features which are a more satisfactory for me over GitHub has in recent years. However, the open source projects must be maintained on Github to get visitors from the Explore.
Take a look at what kind of project are there, what are the good parts of those, and how the current trend is going. If you haven't seen 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 each of those are listing 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 shows popular open sources by language and date range, regardless of the total number of stars. The Trending in Explore Main page shows projects those received the highest number of stars this week in all languages. Getting up here 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 realizable number which your project can also reach.
Focus visitors within days to get on the list by bringing in every community you are in. If you can collect enough number of stars, your project can be on the Trending too. If you released a new project or added features to the project, it is the perfect time to do so. Don't be disappointed even if your project is listed on low. Your project will still get additional visitors. Think the Tranding as visitor incentives based on your rank.
The chart above is a breakdown of visitors at GitHub Insight after I spread a word in communities on Jan. 10. Referring Sites in GitHub Insight gives two weeks total values, so you need to make some calculations to get the numbers you want. On January 10, the day one, almost all visitors are coming from communities I wrote my own. A small github.com part in the chart shows TOAST UI Editor was listed in the Trending from day one luckily. The next day, January 11, GitHub already occupies half. It is damn good incentives from the Trending.
The next day, on January 12, The TOAST UI Editor recorded the #1st Trending Today in all languages. Most of the visitors came from GitHub. From this day on, the visitors coming in from the posts I wrote myself in the community are decreased considerably. On the other hand, as visibility increases, visitors were appearing from unexpected referrers.
The following day, Jan. 13, most visitors came from GitHub. The TOAST UI 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 Vistors from GitHub Topics
Topics show projects in order of the number of stars in a topic. It 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 as from Trending. But it is still worth.
I saw many projects have no Topics. Look for an image below 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. Take JavaScript Topic as an example. There is dinosaur-sized project like FreeCodeCamp, BootStrap, React, Vue and so on. In fact, your project is really x 100 hard to get on the list. The Atom Editor is listed on 10th in JavaScript Topic with 34k stars. It does not make sense to have JavaScript Topic. However, The TOAST UI 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.
# Best Single Line for Project Description
Let's find the Description in the image above again. What is the project description for your project? I had written a description as a long version of the title.(It's a bad idea) Have you come up with your line? Then let's look at the next image.
It is what the TOAST UI Editor looks like on Trending and Topics. Let's look at it from the point of view of visitors. There is an organization, a name, an icon 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 the project.
Final word
Writing documents, Being active in communities, and Utilizing GitHub's tools. The tips I share in this article will help you to make your project better as an open source not only just getting stars. It doesn't mean those tips can make your project popular without the value of your project itself. In fact, those can't do that happen. I hope this writing can help you to find contributors your project deserves.
I think I have a chance to write this article because the former maintainers(Shiren, JungHwan) did a great job for this project. I believe this project already had the value what it has today. And the tips in this article helped the rest. Last month I had a truly special experience as a developer. I would like to thank FE Dev Lab and Dooray! Team for all your support!
ps. Dooray! is currently free for less than 100 users. You can try TOAST UI Editor with it. May the TOAST UI Editor be with you.