Stepping up your README game

READMEs are likely the single most overlooked component of a promising new open source repository. You could have the most amazing project the world has ever seen, but if you don’t leave a good first impression, it won’t be seen. In this article, we’ll look at some of the best practices when it comes to creating a README, and wrap up with a look at some great examples out in the wild. Following these tips in your own projects will help catch the attention of visitors and lead to more users and contributors.

The DO’s and DON’Ts

DO: Make your title short and memorable, but descriptive

In the world of open source development, there’s been a subtle trend toward cute names that don’t describe a project at all, something like “bacon” for a JavaScript graphing library (just to provide a random example). If, for some reason, you think bacon is a good analogy to the way in which your graphing library functions, perfect! Use it! But if not, try finding another word (or make one up) which may describe it better.

A perfect example that comes to mind is Vue. It’s three letters, highly memorable, and very descriptive of the project, despite not being an actual word.

DO: Add a title and (short) description

Really, you can style your title however you feel fits best. I like using lowercase for my repository names, but title case in my READMEs. That’s not everyone’s preference though, and, frankly, it doesn’t matter all that much.

What matters much more is a short description of what your project/library does. Put this description right under your title, before any badges, links, or anything else. Consider this the TL;DR of your repository, and try to keep it under two sentences. For new visitors to your repository, this is going to be their absolute first impression of what your project does — don’t confuse them with unnecessary jargon!

Short and sweet.

DO: Add badges

Badges are small, colorful tags that you can put in your README to show off things like whether your tests are passing, test coverage, technologies used, and various other metadata about your repository. For a full list of the most common badges and an easy interface to create your own, check out the Shields.io website. It even lets you create your own!

Featuring a short description and a few badges.

DON’T: Add too many badges

Having badges is good. Having three lines of repetitive badges, on the other hand, may be a little excessive and can overwhelm readers, drawing them away from the important details in your document. In my experience, 2–5 badges is ideal. Anything more than that might be better suited further down in your document, and certainly doesn’t belong at the top. Choose only the most important badges to feature in the prime real-estate at the top of your README.

DO: Add a logo (if you have one)

Nice logos can really make your README stand out from the rest. There are a few places you can put them: above your title, below your title, on the right next to your title, or really anywhere you find is nice and not too distracting. If your logo includes the title of your project, consider using it instead of a title, but remember to add alt text so that screen readers can still pick up on it.

DO: Add pictures or screenshots

Pictures or screenshots of your project (if applicable) are potentially one of the most important things you can include in your README. For people unfamiliar with the project (or who aren’t quite sure if they want to use it), showing off what it looks like in practice can be very beneficial. If possible, scatter these pictures throughout the README, but try to have one somewhere near the top to help hook in new visitors.

Google’s Cartographer, featuring a nice GIF of the program in use.

DO: Add working demos of your project

If you can’t easily take screenshots of the thing you’re developing (like a non-graphics library or package), try to include a link to a CodePen or other fiddle website so that users can see it in action and play around without installing it.

DO: Add code samples (if appropriate)

It’s often nice to include short, clean, and well documented snippets of code in your README to show users what it might be like to use your library or package. Showing the result of the code in the form of a screenshot or link is also a big plus.

DON’T: Throw in random code blocks

In order to be effective, your code samples should be well documented, with comments and descriptions before and after about what the code does. Assume the reader is not an expert on your code, because they likely aren’t. Again, keep the code samples short and use them sparingly.

Tips and Tricks

Using HTML in Your README

If your README is written in Markdown (in other words, a .md extension), you can mix in some HTML where it may be convenient. Usually using plain Markdown is plenty, but if you want to get fancy with centered titles or images, you’re going to need to get your hands dirty with a little HTML. Take the following example:

Looks pretty snazzy, right? Here’s the relevant part of the README.md:

<h1 align="center">GitPoint</h1> <br>
<p align="center">
<a href="https://gitpoint.co/">
<img alt="GitPoint" title="GitPoint" src="http://i.imgur.com/VShxJHs.png" width="450">
</a>
</p>

<p align="center">
GitHub in your pocket. Built with React Native.
</p>

<p align="center">
<a href="https://itunes.apple.com/us/app/gitpoint/id1251245162">
<img alt="Download on the App Store" title="App Store" src="http://i.imgur.com/0n2zqHD.png" width="140">
</a>

<a href="https://play.google.com/store/apps/details?id=com.gitpoint">
<img alt="Get it on Google Play" title="Google Play" src="http://i.imgur.com/mtGRPuM.png" width="140">
</a>
</p>

Although not everything is allowed in this custom HTML (you can’t use custom styles, for example), it should still provide you with a fair amount of flexibility in order to format your README to your heart’s content.

Use Transparent PNGs and SVGs

While that picture above looks phenomenal with the default GitHub color scheme, several browser extensions add a dark theme. Let’s see what it looks like with the GitHub Dark Theme Chrome extension enabled:

It’s alright, but definitely not as nice as a transparent background. Obviously, a majority of the people visiting your repository won’t have a customized theme, but it’s nice to be inclusive and thoughtful of those who do, especially since it’s often very little work on your part.

Summary

Every author and every developer has their own unique style. This includes all the writing and styling that goes into a README. You definitely don’t have to conform to every rule about READMEs, and the suggestions I gave in this article are likely different than the suggestions other might give. In the end, how you present your hard work is up to you, but hopefully this article gave you some good things to consider.

Some Phenomenal READMEs

Here are just a few repositories (found on GitHub Trending) with very well executed READMEs.