Remaking README from the beginning
How to make a fascinating README file
This article is about what I’ve researched while remaking @egjs/Flicking’s README for advertisement.
If you’re working on some open-source project, I’ll bet, for your reason, each of you are working on great project.
However, no matter how great your project is and how much time you’ve spent on your project, it is no use that nobody uses what you’ve created.
But unfortunately, time you’ve spent on just writing code can’t be directly connected to number of users.
Figure below is part of Github statistics last year(2018). You can check it by yourself on here. There’s an interesting item. It says about 96 million repositories were created by last year, and nearly one third of them were created in the last year.
As statistics tell you, there’s really a lot of open-source that’s been created, and it’s still being made.
Unless you create something totally new, or even if you’ve created something that different already, competition is inevitable.
We also had to try our best to contest our competitors. Flicking is quite competitive library compared to other similar libraries, but it’s not popular at the moment; like Github’s stars are low, npm’s download counts are low, as it’s not advertised well.
Therefore, we tried a lot of things while releasing Flicking’s new major version. We built new demo page, and we did some advertisement like posting release notice to bunch of websites.
One of those activities was rebuilding README.md file from the beginning. Even though it was one of most viewed pages, it was quite monotonous and features of the library were unclear.
In this article, I’ll explain what I’ve researched while remaking Flicking’s README file, based on its structure.
Before start writing README file, what I’ve done first was analyzing other library’s README file.
While touring a large number of Github repositories, I’ve analyzed common patterns in well-made README files, and plus I’ve also collected some uncommon but good patterns. Here’s a summary of it.
The top part of README mainly includes logo, badges, links to your demo/documentation page and images/text that can present the features of your software.
Logo
I think logo is quite important, as it can impress people seeing README file that your project is well managed and lots of efforts are being put.
Flicking also didn’t have a logo before, but we added a new logo with the README update. In addition to above effect of logo that I mentioned, we also designed this logo to show what our library is for, which usually called carousel or slider component.
Badges
Badges represent status of project in small images. In addition to information, you can also create some useful links by putting hyperlink to your badge.
Many badges are available at shields.io, and you can customize your badges like logo, label, color, so check it.
Link/TOC
Links are mainly used to provide navigation to your live demos or API documents. In the case of Flicking, we’ve added an item called “Other components” to promote other libraries created by our team. Likely, you can add other links like your blog, project homepage, tutorial. In addition, the table of contents can be provided when there are many sections to show.
Representative Image
After adding a logo, a badge, and a little bit of explanation of your project to your README, it is often to put a “main image”, to show what your software is for. For example, if it’s CLI program, main image usually show how CLI program is used / what CLI program can output. Or if it’s UI component, It is quite common to show things that can be created using by component.
As Flicking is also an UI component, we’ve demonstrated unique and various UIs that can be created using Flicking, and used them as our main image. We’ve also put links for each of images to show actual code that can make that UI.
Catchphrase / Key features
The key feature is one of the things that users most care about while choosing which library to use. Usually, projects often separate them as independent section as they can be quite large. Though it is also quite common to use catchphrase to show your key features in short sentence. For Flicking, as Flicking’s key features are supporting various environment, like most frameworks, mobile, and PC, we’ve combined them like below figure.
Other items are usually divided into individual sections.
Common sections are:
Features / Goals / “Why should I use this?”
Although this is overlapped with above section, the functionality provided by the library is the most important factor in selecting which libraries to use, and therefore should be emphasized. It is quite typical to provide most powerful features that software provides in the form of a list.
Or, you can show your features with images as shown below.
Installation & Quick start
The two sections are a guide for people who are just about to use the software.
The “Installation/How to Install” section describes how to install the software.
The “Quick Start/Overview” section describes a short code or simple process to run the software.
Although it is easy to overlook, “Installation” and “Quick start” are important items for usability. So, the detailed description like how to install your software in different environments, what dependencies are required and how to install them, can lead to more users.
Contribution
The “Contribution/Contribution” section describes how to contribute to this open source project. Typically, you fill this section by creating a separate file called CONTRIBUTING.md then putting a link for it. You should write some guides on it like code contribution, writing a pull request, code styles and commit style.
You can even create a separate entry called “Contibutors” to show people who actually contributed to this project. In this case, it is usually shown like picture below using an opencollective.com, which is a platform for receiving sponser / backer for a project. There are conditions like project should have star more than 100, and your project should have at least 2 contributors. I think it’s good to use it if you need to.
License
The “License” section represents the license information for the project. You can describes the license you’ve used, but the form is different from one repository to another. You can put a simple link to your LICENSE.md file, or a short version of the license, or even a full text.
The above sections are common to most projects. But there’re some sections not that common but quite cool I’d like to introduce.
Packages
The “Packages” entry provides links to the packages associated with the project. Related packages are relatively hard to find compared to main project. Therefore, providing links to packages can increase convenience to users as well as promote related packages.
Migration Guide
Migration guide from older versions, or other similar libraries can produce same effect as Quick Start. This can lead to more users by securing users who are using older versions or similar libraries. It also can encourage use of newer version.
Roadmap
Roadmap is for explaining project’s future orientation. You can fill this section by creating separate file(ROADMAP.md, COMING-SOON.md), using Github’s Wiki, or managing them in Github Issue then link it.
Flicking chose maintaining them in Issue. Unlike the other two, feedback on the roadmap can be directly received in comments or reactions within Github Issue.
Comparison
As I mentioned earlier, open-source software must compete with other similar software. In particular, if other competitors already have enough users and your software is not, it will be easier to attract users if you can show some numerical advantage over other software.
Ready to Use Examples
This is a method I’ve found in react-stockcharts, where you create a separate repository from the project, put all the demos into the repository, and then put a link to that repository in your README. I think it’s useful when there should be a lot of demos and examples for your project. It can be used as some common patterns for your project, so people can just grab and use them right away like shopping in grocery store. Please check this example.
I’ve introduced a variety of items, but I think it’d be nice to make a selection based on the project.
Other considerations include:
Translation
This is basically translating README files into other languages and provides them as separate files. Although it can provide more accessibility to non-English-speaking countries, it is difficult to manage because every README update requires an update to every language’s README.
Styling
Although there is a limit to what you can express through Github flavored markdown, the more you know, the wider you can express.
For example, the image below is part of MultiSnapRecyclerView’s README file, and you can see that the alignment feature is used to create a unique UI.
You can try styling using the following links:
Besides
There are also tools that automatically create README.md files. It’s true that making README yourself can be burdensome task for your schedule, so I think it’s a good idea to try those tools if necessary. readme-md-generator is an example.
Conclusion
It’s not entirely due to README file reform, but we expect it had contributed to project’s advertising. If you have complex text-oriented README file on your project, I hope you can review the article and get a good result on your new README.
