How to set up a useful README file for your Github project

As a new developer, starting or joining a new project can be a daunting prospect. What programming language is the codebase in, how do you set up the project locally, and what is the project even about? A well-written README file is crucial for any project, not just for new developers, but for everyone. In this article, I will discuss the importance of a good README, and give tips on how to write your own.

Why do you need a README file

As Martijn already mentioned in his previous blog post, the README file is a starting point for any project. It serves as a cornerstone, giving everyone who visits your repository a quick overview.

This often overlooked file is an incredible tool for any project. Not only is it the perfect place for your documentation, it’s also a way for other users to communicate and collaborate. Some examples of why you would include a README are:

  • Explaining of your project
  • Documentation
  • Introduction of your project
  • Troubleshooting
  • SEO
  • Community engagement/involvement when your project is publicly available or open source

Formatting your README files

There are many different ways to format a README, but they all have one thing in common. README.md files are written in Markdown Language. Markdown is a lightweight markup language for formatting text, with a simple syntax. It’s important because it ensures that README files are readable and easy to render on platforms like GitHub. Most README files are placed in a project’s root directory. Feel free to experiment with multiple README files in your project. This could be in the directory for your front-end, back-end and/or microservices.

There is no perfect formula for a README, other than not having one. And while there is no perfect formula, here is a template to start your README file

Key Sections

Let’s start at the beginning, what is the name of your project? If your logo includes the name of your project, you can choose to include just the logo. The choice is yours, just keep the reader in mind.

Table of Contents

The Table of Contents is the beginning of every README. It provides quick links to key sections and helps the user navigate through the document.

## Table of Contents

[Description](#description)
[Requirements](#requirements)
[Installation](#installation)
[Usage](#usage)

Project Description

This section is a general description of your project. What is your project about, and why is this information important to the reader? For a private project, a short summary may be enough, but for a public/open source project, this may be a longer section with more visual elements.

Requirements/Built with

In this section you can outline your project’s prerequisites, code stack and technologies. You can specify which frameworks, software and libraries need to be installed before the project can be run and deployed. Users can properly understand the environment of a project before they even download it.

Requirements:
Node.js v20 or higher
npm v10 or higher
Python 3.12

Built With:
React.js
Express.js
MongoDB
Bootstrap

Getting Started/Installation of the project

This is where you give users a step-by-step guide on how to set up your project locally. Typically, this will include instructions on how to clone the repository, install dependencies, copy the environment if necessary, and get your project up and running. Anything that is needed to ensure that a user can easily run the project on their machine can be included here.

An important tip here is to put your code in code blocks. This way, a user can just copy and paste the code and follow along. An example of this might be

  1. Clone the repository
git clone https://github.com/your-username/your-project.git
cd your-project
  1. Install dependencies and start the project
npm install
npm start

Usage

Does a user need an account for the CMS? Do you need to log in to a third party application before you can use the API in the project? This is the section to mention this. For example, here at Norday we use Laravel Nova as our CMS for some of our projects. This is the place to give the commands to create an admin account for the CMS.

php artisan nova:user

Extend your README

As mentioned above, there is no one right way to write a README file for your (Github) project. This gives you the freedom to include as much information as you need. Think about adding your project’s testing process, FAQs, your API endpoint structure, or copyright and licensing information. It’s up to you to decide what to include in your README, as long as it’s important to the readers of the project.

Update README during production

Last but not least, do not forget to update your README. A lot can happen during the course of a project. The instructions for building your project may change because you have updated your framework, or an API endpoint may have been removed because it was no longer needed. These changes should be added to your README so that the information is always complete. So for every pull request, ask yourself: do I need to change this in the README? This will not only make your life easier, but also that of the (new) developer after you.

Conclusion

Coding can be a magical world, and a well-structured README can make it much easier to navigate. It can be crucial for working with other developers, and is a tool not to be underestimated. Always include a README in your projects, if not for yourself, then for the new developers in the world like me. We will thank you in advance.