Introduction

If you're familiar with GitHub, then you know what a README file is. But if you don't know what it is, you can think of it as the introduction to your repository. It's very helpful that while looking at someone's repo you can just scroll down to their README file and have a look at what their project is all about.

It's crucial that your project gets introduced properly because if it isn't, the chances of someone pressing on the repo are low. That's why having a good README file shouldn't be overlooked and you should spend a good amount of your time on it.

In this post, I am going to share some tips with you about how you can improve your README file, and hopefully, it can help you with your repos.

Choose an easy name for your project

Before we dive into the README.md file let's quickly mention the name of the project itself.

When people search for different projects, the last thing they will want to see is:

"cool-javascript-game-about-colors-and-rgb-colors-and-even-more-colors"

Now I know that this example is a little over-exaggerated, but you get the point. No one is going to press on a repo with such a long name. It's best if you try to have a simple and short name for your project that gets right to the point.

So for the example, above we could just use:

"javascript-color-game"

A name like this has a higher chance of getting clicked on and taken a look at. So make sure that your repos name is simple and straight to the point.

Give a descriptive summary of your project

Now that we have the repo name cleared out, let's focus on the README.md file!

When someone visits your repo they can scroll down and read the README file. It should have a description of what your project is. But you wouldn't want it to be too short. And neither should it be too long. Now if it's a very big project then by all means you should give a proper explanation of what it is and what it does. But in most cases, it should be a well-written and structured text. There are five steps that I would recommend you follow while writing your README file.

Step #1

Write a quick introduction to what the project is about. For example, if you made a to-do list using JavaScript, write about that. But don't get into too much depth.

Step #2

Write what your code uses. For example HTML, CSS and JavaScript.

Step #3

Write a few more details about the project. Write things that would make you take interest in the project.

Step #4

Write something about yourself. You could say where you work, what your goals are, or share some of your previous projects. It's okay to share what you have created or what you are trying to accomplish

Step #5

And finally, use images. Show the reader what exactly the project is. Just by reading about it isn't going to get their full interest. But by seeing an image of it, they will be more likely to get more into it.

Conclusion

And these are some tips about writing a good README file. It's very important that you get comfortable writing these things. It could help you change the level of interaction your GitHub repo gets.

I hope that this post has helped you in improving your README files and I hope to see some great repos with great README files out on GitHub soon.