Did you notice, that every project’s readme is almost the same? Users rarely go through all of the readme’s contents and reach the end. How do you breathe life into your readme and attract users’ attention to what’s in it?
Here are 5 simple tips you can easily implement in less than 20 minutes. There’s an exclusive tip at the end of the post, which will make your readme stand out of the crowd.
1. Project summary
Right after your main headline in the readme, insert a short project description. In a perfect world, it should be 1 sentence, but I guess 2 is fine too. Here are a few examples:
Your own Travis CI to run tests locally.
Capture website screenshots.
2. Quick look
Similar to Quick Look in OS X, let users have a quick peek on how to use your project. Don’t force them to read full-blown documentation to get a sense of what this thing does.
Try to provide a self-explanatory code example, ideally less than 30 lines.
Here’s how got does it:
const got = require('got');
// Callback mode
got('todomvc.com', (error, body, response) => {
console.log(body);
//=> '<!doctype html> ...'
});3. Project logo
This requires some time, but in my opinion, it’s worth the effort. To me, a customized hand-picked logo shows that the author really cares about this project. It shows, that the author took an extra step to make his project look good.
Does project logo help your users with understanding your project somehow? Probably not. But it certainly brightens up the boring black & white readme.
4. Show it off
If your project has some interactive output (or any valuable output, actually), make sure to record that as a gif and insert into your readme.
One picture is worth a thousand words. A video is worth a thousand pictures.
I had this problem with Trevor - a local Travis CI to test code on multiple Node.js versions. When I started writing a readme for it, I struggled to explain in words how it looks in action. So I recorded a simple gif showing the live output of this tool.
Tip: Use Kap for recording gifs. It’s a beautifully simple app that does the job well.
Thanks to this demo gif, I only have 2 short paragraphs explaining what Trevor does.
5. Interactive user guides
Now this one is a killer.
What if code examples in your readme were interactive? Imagine, a user can play around with your example code, execute it and see the output live. And all this magic happens right in the browser, without having to install anything.
Today all that is possible thanks to RunKit.
RunKit is an interactive Node.js playground in the browser. You can include dependencies from npm, just like you would in any other Node.js project. Think of it as an interactive readme file.
Try converting one of your readmes into a RunKit notepad and see how well it works for you!
Implement these simple 5 tips and I guarantee, that you’ll like your readmes more.