The structure of a good ReadMe file

The Readme file is normally the first thing anybody sees in regards to documentation because people would find our modules through NPM’s page, Yarn’s or even looking at our components on Bit’s component marketplace.

With that in mind, there are certain things you need to take into consideration to optimize the reading experience of your potential users (i.e other developers).

What’s the name of your library?

That’s the first thing you need to show. The title of your Readme file has to be the name of your project. That’ll give the user a clear indication that they’ve found what they’re looking for.

You do that using a single # at the start of the line:

# This is the title

Do you have a website with extended documentation?

The second thing you should be showing, if you having it, is the URL for your website. There is no point for your user to keep going through a simplified, and sometimes — even though it shouldn’t — outdated, documentation. If there is a place where they can browse and get all the details they need, make sure you add the link right at the start (some people even add it as part of the title itself):

# My library [www.myurl.com](http://www.myurl.com)

The above line gets rendered into:

What is your project all about?

The first thing your readers need to read, right after the name and URL (if there is one), is a brief description of your project. Keyword there being “brief”. Don’t go all in and explain the motivation behind it, the struggles you went through and the journey you took to get here. Just write a single paragraph explaining what the library is meant to be doing. That’s it, if you want more, you can add a link to an external file where you cover all of that. This is not the place for it.

Installation / requirements

Most Node modules will simply require a quick npm install call. However, some might have other requirements, such as a particular OS, or other utilities to be installed (such as a module depending on ImageMagick for example). Here is where you quickly list all of that.

Using the library

Now it’s time to cover use cases. Start from the easiest one, chances are your users will just copy & paste your example into their code, so don’t over-complicate it.

And use code blocks, most Markdown templates for places where your library will be published will accept language suggestions, so add them and your code will be highlighted:

```js
//A comment 
function dummyFunction() {
}
```

That code can be rendered like this thanks to the language suggestion:

Start with the most basic example, and keep increasing the complexity if there are edge cases. Just remember to keep the explanation around them simple, concise and if you need to explain some concepts in-depth, link to other pages.

Contributing to the project

This section is optional, because you might not be interested in other people making contributions, but if you are you have to explain the process here.

Normally you’d want to have some form of process in place because otherwise developers will jump in and send their PR’s in very different ways with very different standards. That in turn means you’ll spend countless hours reviewing them and fixing them to match your coding standards.

So to avoid all that pain, make sure this section is crystal clear and explain:

• The coding standards you’re using.
• The content the PR should have (i.e other than the code changes, you probably want unit tests around that, updated documentation, etc).
• How often you check and review PRs. This is especially useful for people using and needing a certain PR to be approved. Setting the expectations from the get-go will avoid problems with developers thinking they own your time and you should be working full time on your open source pet project.

Make sure to add any other peculiarities you feel like adding here regarding interaction with developers. Maybe for a PR to be valid, you require an issue to be open, then explain that here as well.

By being clear and concise you’re making sure everyone knows how you work and how they need to work if they have any hopes for their contributions to make it to the next release.

Licensing terms

We often forget about this section, but it should be there every, single, time. Learning about Open Source licenses is not that hard, this website for instance makes it very easy for you to pick the right one based on your expectations and needs.

But if you don’t have one, you’re leaving the door open for anyone to do whatever they want with your code. And that can be dangerous, or heck, it can work against you. Maybe you have the library to be used for the next 5 years by all Node developers and you’re giving it away without even knowing.

Take the 5 minutes you need to pick a license and add it at the end of your Readme. You’d normally also add an extra file covering the entire license inside the repo and you can link to that file from this section.