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.
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) 💪.
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
- 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.
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 cases & quirks
- 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
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. 🚀
The latest Tweets from Joaquim Ley (@JoaquimLey). I create bugs on #Android for a living at @Tonsser. Besides coding…twitter.com
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!