How to use the README.MD as a cover!

Your project ain’t no GQ but you aren’t Brad Pitt either 😎

So you finally created your open source project, you feel really proud (and you should 👏), and now it’s time to make that repo public and start to get some feedback, you can’t wait to see other people opening issues, creating pull-requests etc. But for some reason, not even one star gazer 😕?

“Don’t judge a book by its cover” — Also applies to software projects but that doesn’t mean it can’t be pretty. Here are some of my thoughts on making it a bit more appealing to the 🌎.

1. I like to start with visual stimuli 👨‍🎨

  • Since I’m an Android developer its easy for me using the app icon usually works the best, but you can use any logo/image. It’s a matter of preference, but having an image either before or after the title drives more engagement.
App icon before title and metadata badges — Avenging on GitHub

2. Use metadata badges

  • These are both useful and flashy 👆, it’s a simple and beautiful solution to provide some key information to visitors. A lot of services/tools already provide you with badges (e.g. Travis-Ci, codacy just to name a few), but you can also create your own custom badges this is where Shields.io comes in, give it a try it’s EZ (but don’t over do it) 💪.

3. Simple description

  • What the project is/does along with the motivation (maybe these two are correlated 🎉).

4. Now for the most important part

  • This is where you actually get people to engage and use your LoC on their own projects: A visual example (when applicable), install/import process and finally a “how to use” — This is where you usually describe your public api.
Example gif followed by Import/Install and public api — FabOptions on Github
Be as efficient on your description as possible, this the time to show that is both useful and easy to use your project 💪. If you find it too hard to put into words how to use it, maybe it’s time to simplify (of course this depends on the complexity of the project, so be reasonable and take these words with a grain of salt, adapt to your own case).

5. After the “How To”, it’s time to discuss corner casesquirks

  • These could be issues under development/fixing or how it just naturally turned out to be, anyway it’s better to inform your users beforehand and prevent some developer frustration 😓.

6. Sample and contributing 🙏

  • If possible provide a working sample e.g. A website using your UI component, an app or an example with graph showing how quick your algorithm is.
  • Guidelines how to contribute, maybe provide an ISSUE_TEMPLATE.MD
  • License

Now it’s time to get the word out, it’s open source and probably won’t get you any money, but it’s not getting discovered by magic! Talk with your fellow devs about your new project, post on social media and forums. 🚀


Hello! My name is Joaquim Ley, I’m currently based in Lisbon, Portugal.

If you liked this article hit that 💚, if you know someone who might extract value please share, I’ll be looking for your opinion and suggestions in the comments, feedback is always welcome.

If you would like to see more content from me, 👊 the follow button!