How to Write a Great README File for Your GitHub Project

I believe there isn’t a developer out there without a GitHub account. Or at least it’s almost impossible not to be on platforms like GitHub/GitLab in your company. Adding a Readme file to our public or private repositories is also part of the job’s nature.

If you’re asking, “What is a Readme?”: README is a text file that introduces and explains a project. It contains the necessary information to understand what the project is about. It’s a file formatted in Markdown.

I’ve had a GitHub account since my early years of coding. On this account, I’ve created a total of 63 private and public projects. Recently, I noticed that none of the Readme pages are the way I want them to be (some don’t even have one, others don’t describe the project properly, and most are not written from a professional perspective), and all of them are different from each other.

So, I declared a personal “GitHub Readme Campaign.” As part of this campaign, I will both refactor my previous projects and update their Readme files.

First Step

The first step I took for the Readme files was to create a format by combining my criteria with industry standards. While creating this format, I reviewed existing Readme templates on GitHub and customized my template by making adjustments to the one that has the most stars and is also my favorite.

https://github.com/othneildrew/Best-README-Template

For various badges, I benefited from these repos:

https://github.com/Naereen/badges

https://github.com/Ileriayo/markdown-badges

If I wanted to create my badge, I used the badge creation area from this link:

https://shields.io/badges

---

My README Format

The link to my README format:

https://github.com/aysedemirel/README-Template

I customized the general template with my touches and created my Readme format. The final details are as follows:

• Language Badge: While publishing my projects, I generally create content in English, but most of my followers are Turkish. So, I thought adding language options with two badges would make it easier for my followers.

• General Project Information: This section provides a brief line about the number of contributors, fork count, star count, open issue count, license used, and a badge for my LinkedIn profile.

• Short Project Description: To add some visual perspective (for just fun) to each project, I include an icon, a brief project description at the start, a link to the project documentation (I’m thinking of creating a wiki for some projects), a link to the live demo if there is one (thanks to GitHub Pages), and links for requesting bugs or new features (in my opinion, contributing doesn’t necessarily mean developing a new feature, requesting a new feature or reporting a bug is also a contribution).

1. Table of Contents: As with any documentation, I link the headers before diving into the main content :) Creating a Readme template is a step towards taking my GitHub page more seriously (Actually I’ve always taken it seriously, but I was more focused on content over documentation and adding projects related to technologies I’ve just learned. In my new phase, I plan to produce projects in areas where I’m an expert). That’s why my Readmes will have a bit more of a technical documentation feel.

2. About The Project: This is where I provide a detailed explanation of the project’s purpose and what it does. If there are any screenshots, I add them here to show the expected result without needing to run the project.

3. Built With: This section lists the programming languages and technologies used in the project. While GitHub has a “Languages” section, my goal here is to also list major libraries and frameworks (for example, if Java is used, I want to see that Spring Boot is explicitly mentioned in the Readme).

4. Getting Started: This section explains how to set up the project. Subsections include 👇

• Prerequisites: A list of databases, libraries, operating systems, etc., used by the software. You will find how and where to download these here.

• Installation: Once all prerequisites are ready, this section explains how to install and make the software fully operational.

• Executing Program: This part explains how to run the software.

5. Usage: Detailed explanations about the software will be provided here. When necessary, I’ll use UML models such as class diagrams, use-case diagrams, package diagrams, and sequence diagrams. If the software is a library, you’ll find code examples showing how to use the library in this part.

6. Roadmap: This section lists milestones within the project, marking off completed ones. In general, I plan to open all tasks as issues so those who want to contribute can check the issues.

7. Contributing: This is the section explaining how you can contribute.

8. Top Contributors: Contributors are invaluable :)

9. Contact: This section contains my contact channels for any questions or collaboration requests.

10. Acknowledgments: No project comes out of thin air. I heavily rely on certain projects or documents. This section serves as a reference area where I give credit to the sources I’ve used.

---

With this study, I’ve created the template for documenting my GitHub projects. Now it’s time to refactor all of them and create their documentation. I will continue to share my experiences here during this process. See you in future posts, bug-free days ahead! :)