< Back to blogs

Guide to a simple Readme

Posted by Tejas on 2020-11-29

In an open-source world, the importance of public cloud version control is a boon. As most might agree, Github (or any ecosystem of git) has played an important part in the Tech industry. Contribution to open source has kept the tech growing in a direction of continuous improvement with seamless collaboration.

This said, it's our responsibility to well document our contributions, and the Readme markdown file (readme.md) is the face of our repository. Through this blog, I will try to give a guide to write a simple but effective readme document.

Why is it so important?

Because it's the first thing people would look at when they come into your repo. (As said - First impressions are important! ) People lookout for this file to get a brief of what your repo would be doing and how they can utilize it. And if you are trying to showcase your work, and want more audience, be sure to put a lot of thought into this file

How did I come up with these?

As always, observe the best! I've gone through several repos which are trending, highest starred, and most spoken about. From these, I have collected a few common but very important pointers which I'm going to discuss.

Before I start, I have two sets of contents which I will share, one - these pointers are basic and I would highly recommend to "MUST HAVE" in your repos two - these are good to have and will make your repos look much better

Straight to the MUST HAVE in the readme file

Title

A good title in big and bold fonts will help the reader have it in mind. Try to keep the name much user-friendly and short (Not very vague either).

Description

This would be a very important part of your readme. It should potentially try to explain your software's most important aspects. (what problem it is solving) Try to keep these sections away from took much of technical terms which the user might feel overwhelmed. (Not if your software is a very specific pick) It should not be very long but concise enough to express your thoughts. It's also good to highlight some of your key features in this section.

Tech stack

As the user is most likely to look out for using your code, it would be best to describe your tech stack. It enables the user to analyze the usability of their ecosystem. Also, this will invite interested people to go deeper into the code.

Installation / Usage guide

Once the user is interested to try out your work, you should give clear and precise steps involved to use your work. This would involve details about setting up the dev environment (All the things needed for your software to work) Installation steps with code snippets if necessary and A brief walkthrough of how to consume your features.

Now, the good to have features

Pics/ gifs/ screenshots

As title, these are somethings that you must try to include so that it remains in the user's mind for a much longer duration.

It might include: Credits

In most of the cases we would have people/projects whose presence made your product much better than where it started. Although open-source it's a very good humane thing to call out and appreciate people's efforts

Contribution

this section, you will have to lay down the guidelines in which you would like the contributions to be done to the repo. Or also if you are not open to any contributions at that particular point in time, it is good to mention and save the efforts of very open-hearted contributors.

Copyright and license

If your product is particularly has a restricted usage policy, make sure you highlight them clearly in this section. There are a list of readily available license templates available for usage

Conclusion

Writing a readme would take very less time compared to building your project but has a lot of value and impact on its usage. Let's be wise and responsible while pushing code to the world.

Thanks for reading! If you like my content or have any suggestions, please do share and connect with me on links at the footer.



< Back to blogs