May 5, 2017 / Reading time: 3m

How to use the README.MD as a cover!

opensource

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.
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) 💪.

Shields.io: Quality metadata badges for open source projects
We serve fast and scalable informational images as badges for GitHub, Travis CI, Jenkins, WordPress and many more…shields.io

3. Simple description

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

4. Now for the most important part

    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. 🚀

    Share