This is an article about READMEs.
First things first, why I am talking about READMEs here?
A README is probably the first thing consumer sees on the repository, so as the author of the module it is our responsibility to show them exactly what they need and how can our module fulfill their need. Our job is to:
a) tell them what it is
b) show them what it looks when it's live (a demo gif may work here)
c) show them how they use it
d) tell them any other relevant details
Feeling lazy, sorry dude!
NO README, NO ABSTRACTION 💁♂️
If you don't put a satisfactory README then developers have to look and deep dive into your code which is not a pretty thing to do in my opinion. The developers or consumers want to see your working module before they look into your code so it's better to use a little abstraction.
Okay, I will write one but how to write it?
Here it goes 👇
Project title
A little info about your project and what it is about.
Features
Tell the consumer about the unique features of your module and how it will solve their problem.
Tech Stack
Mention all the technologies you used in the project.
Demo
Add screenshots and demo gif of your working module. Trust me, this will add good value to your module.
How to use
Create a simple and easy to understand guide for consumers if they wish to interact with your working project.
API Reference
If you're using an API in your projects, tell the consumer what it does, and add a link to API docs if needed.
Above mentioned points are enough for beginners who are starting their coding journey. You should keep in mind that adding links, demo, images, references, and interactivity will make you a better developer.
Some resourceful links coming your way 🚀
Articles
1) "Art of Readme - Learn the art of writing quality READMEs" - Stephen Whitmore
2) "How To Write A Great README" - Caleb Thompson
Examples of awesome READMEs
1) aimeos/aimeos-typo3 - Project logo. Clear description of what the project does. Demo screenshot. TOC for easy navigation. Easy installation and setup sections with screenshots. Links for further reading.
2) ai/size-limit - Project logo, clear description, screenshot, step-by-step installing instructions.
3) iharsh234/WebApp - Project landing page. Clear description of what the project does. Demo screenshot. Simple install and usage sections. Includes an examples section with common uses and a mobile demo section.
That's all folks, hope it helps the new comers!
Top comments (0)