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.

A common appearance of README files

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

Flicking’s 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.

Flicking’s links

Representative Image

Flicking’s main 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.