How I Organize README

Must have sections, badges, flow.

I have a lot of projects, mostly NPM modules. If you browser through www.npmjs.com/~bahmutov you may notice how uniform all my README files are. Every module has a README file that follows pretty much the same template (thanks to Yeoman generator-node-bahmutov I use to scaffold new projects).

Typical README with several must-have sections

The main sections top to bottom are:

  • head with name and description
  • badges
  • requirements and install instructions
  • how to load the code
  • quick example
  • legal matters

Let me quickly describe what each section does.

Head

Most people looking at the README are not your users. Maybe they were searching for something else and stumbled upon your repository. In either case, the first thing my README has to answer for everyone is "what is this?" The most important information everyone should see right away is module's name and description.

1
2
3
# mocha-banner

> Terminal-wide banner with test name before each Mocha test

People who are NOT looking for a Mocha utility will leave after reading these two lines. People who are looking for a big "in your face" messages to make their Mocha output easier to understand will continue reading.

Badges

No one wants to waste time learning and using an unreliable library. Having a few badges that tell the user that the project has CI system, has recently published version and follows certain conventions is a good way to earn user's trust. I wrote about badges before so here are the only 5 badges I always use.

I start with a large NPM badge with the main information: latest published version and when it was published.

NPM module stats

Then I have 4 inline badges that signal the quality of the module.

badge description
[![Build status][ci-image]][ci-url] I only use NPM modules with a CI system setup. I hope it stays green.
[![semantic-release][semantic-image]][semantic-url] module uses semantic-release to publish.
[![js-standard-style][standard-image]][standard-url] linter catches silly JavaScript errors.
[![renovate-app badge][renovate-badge]][renovate-app] this module has its dependencies updated automatically.

Here is the Markdown markup for these badges. I usually keep the urls at the bottom of the readme. Only the package name and username and repository names have to be updated in the urls.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[![NPM][npm-icon]][npm-url]

[![Build status][ci-image]][ci-url]
[![semantic-release][semantic-image]][semantic-url]
[![js-standard-style][standard-image]][standard-url]
[![renovate-app badge][renovate-badge]][renovate-app]

[npm-icon]: https://nodei.co/npm/mocha-banner.svg?downloads=true
[npm-url]: https://npmjs.org/package/mocha-banner
[ci-image]: https://travis-ci.org/bahmutov/mocha-banner.svg?branch=master
[ci-url]: https://travis-ci.org/bahmutov/mocha-banner
[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[semantic-url]: https://github.com/semantic-release/semantic-release
[standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
[standard-url]: http://standardjs.com/
[renovate-badge]: https://img.shields.io/badge/renovate-app-blue.svg
[renovate-app]: https://renovateapp.com/

Requirements and install

This section tells what version of Node (and NPM) is required by this module. Projects that set strict engines option in their .npmrc will not be able to install dependencies that need newer versions of Node. Also I show the install command to let people know if the module is meant as a production or development dependency. Copy and paste into the terminal and go!

Loading code

Again, as a courtesy to the user, I want to quickly show how one can load the module. Is it a function or an object? Maybe the module is doing global registration?! Do not make me think, just show me so I can copy and paste into my code!

1
2
// include somewhere at the beginning
require('mocha-banner').register()

Helpful.

Show an example

The reader is still trying to decide if your module is what they need. Showing the most basic "hello, world" example gives this last bit of information, hopefully. Just put the most typical basic example to showcase the main benefit or use of your library.

Example section

Legal

At the bottom of the README I put links to my profile, this blog, etc. I also clearly tell what license this module has. Pretty much all my software is published under MIT license, and the users should know it. I also make sure the package.json file has the license specified to make life easier for audit tools like license-checker.

Links and legal section at the bottom

Final thoughts

The README should answer quickly the following questions

  • what your library is doing?
  • can it be used in the user's application?
  • how it should be used?
  • are you allowed to use it?

And that's it! Remember, you are not there to answer these questions, but your README text is.

More information