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).
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 | # mocha-banner |
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.
Then I have 4 inline badges that signal the quality of the module.
| badge | description |
|---|---|
 |
I only use NPM modules with a CI system setup. I hope it stays green. |
 |
module uses semantic-release to publish. |
 |
linter catches silly JavaScript errors. |
 |
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 | [![NPM][npm-icon]][npm-url] |
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 | // include somewhere at the beginning |
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.
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.
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
- I have recently made a presentation at Confoo Canada about my NPM workflow, check out the slides
- I love semantic release and have written a lot of blog posts about modular development
- Automate good readmes using a Yeoman generator, like my generator-node-bahmutov