Hi, You are probably here because your project was rejected due to a bad README.
Its fine, We are all learning.
Is my project rejected because the length of my README is too short ?
You might interpret this after reading the rejection feedback. But that's not the issue ! READMEs are supposed to be to the point.
huh ?
Yeh, When we say that the README is a bit short or not detailed enough. We mean that the README is not
matching the OSS standards.
Open Source Software aka OSS projects should have a README which is detailed enough enough so that if any person from any place in the world, lands on your GitHub repository. They should easily be able to understand a lot about the repository
READMEs are supposed to make a newbie understand what this repository actually is.
So, whenever you are writing your README. Ask this question to yourself.
Is this README enough to make a newbie familiar with this project ?
So, How to make a readme like this ?
Its easy, there are some good practices that you should follow while writing a new README
Always try to include these sections in your readme :
-
Title of the project
-
Screenshot (optional if its just a OSS project, Some hackclub YSWS might require you to add this tho)
-
Motivation (optional) : Why are you making this project ?
-
Features : What are some cool things in this project ?
-
Installation : How can somone run this project on their own pc locally ?
-
LICENCE : Which licence does this project use ? The MIT LICENCE is usually reccomended.
-
Copyright : Who owns or maintains the project ? You usually write "made with love by [NAME]" here.
You can also make your Readme look more beautiful by:
-
Adding the logo of the project
-
Adding badges
-
or using some animated SVGs or GIFs in the readme.
Examples of some good READMEs
You should refer to this simple readme template
You can use your own imagination to write a good README. You can refer to this template made by me !
How to write READMEs
to make a readme make a file called README.md in your repository root. Notice the ".md" in the file, That's Markdown
What's Markdown ?
Markdown is a lightweight markup language used to format plain text. Instead of using complex code or a visual editor (like Microsoft Word), it uses simple keyboard symbols (like asterisks or hashtags) to make text bold, create lists, or build headers, which are then easily converted into web-ready HTML.
How to write Markdown ?
This is a great Guide to Markdown. It will take you 3 minutes to learn the markdown language.
Some tools That will help
Markdown writer : Please dont use this tho.
Finally, let's conclude this guide.
Last Updated: June 26, 2026
Did you know That I write all my blogs in 100% custom css without any framework.