How to add a good readme in your GitHub projects

Do you guys edit and customize your GitHub README file? If yes, then you're already on the right path! But if you don't, then let me guide you on this topic in this article.

If you follow these guides, recruiters will only call you (I'm just kidding, btw).

Let’s start with answering a common question that will come to your mind: Why should we add a README?

Well, to understand this, think about it this way: when you visit a GitHub project that has no README, you'll find it difficult to understand what the project is about, what the features are, and many other important details. A README acts as a guide for everyone, explaining what your project is all about.

Now that you've got the answer, let's continue with what to include in the README file?

1. Introduction

Start by writing a brief introduction about the project, highlighting what the project is about and what you used to build it (that's enough for an introduction).

Example:
This is an e-commerce web application built using React and Node.js. It allows users to browse products, add them to the cart, and complete their purchase.

2. Features

Include all the features your project has. For example, if you've built an e-commerce store, you can mention:

• Product listings

• Add to cart

• Add products to favorites

Example:
Features include:

• Product search and filtering

• User authentication (Sign-up and Login)

• Order history and tracking

3. Tech Stack

Mention all the main tech stack you used in the project.

Example:
Tech Stack:

• Frontend: React, Redux

• Backend: Node.js, Express

• Database: MongoDB

• Deployment: Netlify for frontend, Heroku for backend

4. The Process

Start by writing a story of how you began the project and how you ended it in a brief way. This gives context to the project and highlights your thought process.

Example:
I started the project by planning out the features and then setting up the backend. After that, I focused on the frontend UI and integrated it with the backend services. Once everything was connected, I tested the app and deployed it.

5. What Did I Learn

List all your learnings that you thought were new for you and explain them so that your concepts become stronger.

Example:
I learned how to set up authentication using JWT in Node.js and how to handle complex state management using Redux in React.

Pro tip: If you want to smoothly write the Process and What Did I Learn sections, document your journey while building the project so that you don’t forget important details when writing the README later.

6. How to install and run the project

In this section, you should include the following:

1. Clone the Repository: Provide the command to clone your repository to the user's local machine, such as git clone <repository_url>.

2. Install Dependencies: Explain how to install the required dependencies or packages for the project. For example, for JavaScript projects, you can include npm install or yarn install.

3. Setup Environment Variables (if any): If your project requires any specific environment variables (like API keys, database configurations, etc.), provide details on how to set them up. You can mention creating a .env file and what keys/values need to be added.

4. Running the Project: Describe how to start the project once the setup is complete. This could include commands like npm start or node server.js or any other instructions specific to your project.

7. Resources Used

Here, you can list all the tools, libraries, tutorials, and any other materials that helped you build the project. This could include documentation links, third-party services, frameworks, or anything else that was crucial to your project's development.

8. Licensing (optional)

You can mention the type of license your project is under (if any). For example:

• This project is licensed under the MIT License.

If your project is open-source, include details about the permissions, restrictions, and how others can use your code.

8. Contributing (optional)

In the Contributing section, provide guidelines on how others can contribute to your project. You can include steps such as:

• Fork the repository

• Create a new branch for your feature/bug fix

• Open a pull request with a description of what you've done

For example:

• Contributions are welcome! If you’d like to contribute please follow these steps:

  1. Fork the repository

  2. Create a new branch

  3. Make your changes and create a pull request

This helps others understand how to contribute effectively to your project.

8. Live Demo

You can attach a video here so that the readers will get an idea of how your app works.

Example:
Here’s a quick video demo showing how the app works:

Note: You can replace the headings and add your own if necessary. It’s entirely up to you but this is the Readme structure which I usually follow.

What will you get by doing this?

• People will be impressed by seeing your project’s README files (You’ll get attention!).

• You won’t have to explain your project verbally (the README file will do it for you!).

• You’ll stand out as a developer if you do this.

• Most importantly, you’ll learn how to write documentation, which many people find boring (but it’s very important!).

What to do now?

Go and add descriptive READMEs to all your GitHub projects because if not now, then when?

Conclusion

Hehe, you’ve reached the end of the article. I hope you liked it and enjoyed reading it because it took me a lot of time to write. So, don’t forget to like this article, comment (if you’ve any suggestions or issues), and follow me (follow me to get updates whenever I post new articles).

You can also visit my GitHub profile to get an idea of how I document my projects. Here’s a reference link to one of my project’s README: [Project Readme].

Thank you for reading 🤍

Stay connected with me for more articles like this! - Rumaisa Naveed