Writing an awesome Readme📄 for your side projects
You have been contributing to open source by hosting your projects on Github for some time now. That’s great! 👍 But my question is, do you take some time to describe what your project does?🤔 Or even how to run or install the project to guide anyone who interested in the project? No! I have been there before.🤫 I almost always ignored the readme file if present or forgot to add it at all to the projects I build on the side.
The importance of having a well-structured Readme file
It is important to note that writing a readme for each project helps:
- Contributors👨💻 who might be interested in your project understand what your project is about and even contribute to it.
- Having a nice-looking readme helps your project to stand out and attract the right people to contribute👨💻 to the project.
What areas should a basic Readme cover?
Every readme should cover at least the following:
- A description of what the project is about
- How it looks (screenshots 📷, gifs, etc.)
- Instructions on how to run or use it👨💻
- Should contain other relevant details (code samples, tech framework, credits, etc.)
Project Title: 📛
The name of the project
Live Link / Demo Link: 🔗
Add a working link of the project if it is hosted somewhere on the internet :earth_africa: right after the title so that people can quickly access and have a feel of what and how the project works.
Table of Content: 📑
Add a list of relative links that connect to other sections of the readme file. Ignore if your readme is not too long. But I will advise you to add this as your readme file may grow in length over time
About the Project: 📚
Give a brief description of the project. What was the reason or motivation behind the creation of the project?
Screenshots: 📷
Add a picture or short video(gif) demo of how the project works.
Technologies Used: ☕️ 🐍 ⚛️
List the tools and technologies used to build the project. Doing this can help developers familiar with these technologies to contribute and help improve the codebase.
Setup / Installation: 💻
Concisely and clearly, list the steps needed to run the project.
Approach: 🚶
Briefly explain how you went about the project. The design patterns implemented and code styles used.
Status: 📶
Mention the status of the project. That is whether the project is completed or in progress.
Credits: 📝
Giving credit is very important. Don’t forget to give credit to anyone who inspired or helped one way or the other in contributing to the project. Is the project based on course work? Or an expansion of someone’s previous work? Don’t hesitate to add links to the repository or people who played a role.
License: ©️
Add any license agreement information. Example (MIT, Apache).
Below is an example of a readme file in markdown:
Final Words:
Thank you for staying with me up to this point. Suggestions and feedbacks are always welcomed.😃
Credits:
Image by: https://unsplash.com/@kellysikkema
