How to Write a Good README File?

Problem

The README file is one of the most important files in any programming project. It is a text file usually written in Markdown that introduces the project and explains its contents. It helps people understand how to install and use your code, as well as how they can contribute to the project.

Why write a README?

Back in 2010, Tom Preston-Werner advocated for writing your README first, before you do anything else. He argued that, despite the programming methodologies and project management practices like TDD and SCRUM, it is better if others can understand your project right away through a README description.

Writing a README is necessary to create a good application. It will shape what you need to do later in the project.

As Preston-Werner said, it would be much easier to start writing the README when you start your project, that's when you have the most motivation. When you finish your project, writing the README will be like another task, another small job. That will reduce your interest in writing it.

But regardless, you still need a README file that conveys the complete content, because very few people will review your code to understand how it works. It takes time, and they may not have the technical expertise to understand it.

Furthermore, it's not just new developers who are interested in your README. Recruiters also do, they will look at the README to understand your skills. The README once again shows your professionalism.

Even when you are working on a personal project, README is still important. Imagine coming back to continue the project after a while. With a good README, you will know right away what the project is doing and help you get started immediately.

How to write a README?

Writing a README file needs to have a clear and concise structure, which sometimes depends on the ability and aesthetics of each person.

Below are some essential things when you write your README:

• Title
• Introduction (It explains what it is and why you are writing it)
• Install (How to install?)
• Use (How to use?)
• Technologies Used (Libraries, versions, etc.)
• Acknowledgments (It's where you write acknowledgments, links to other inspiring articles that helped you complete the project)

Those are the minimal necessary things to help you and others. Besides the above sections, you can add sections that you think are necessary for the project. For example:

• Table of contents (Useful if your README is long)
• List of features
• Examples (Code snippets or images demonstrating usage)

Examples of good READMEs

Here are some projects on GitHub that have well-presented README files:

• ai/size-limit: Complete images and detailed explanations.
• crelies/AdvancedList: Concise explanations and eye-catching use of emojis.
• maxvoltar/photo-stream: Nice table of contents and sufficient sections.
• release-it/release-it: Includes GIF and detailed instructions.
• ArmynC/ArminC-AutoExec: Well-organized list of features and clear descriptions.

Additionally, there are tools available to help you structure your README in a more organized way. One of them is readme.so. It is a tool that assists in creating a README file with all the sections provided, which you can experiment with directly on the website or refer to the sections the tool offers to manually create your own file.

Readme is an essential file for your programming projects, even if it's just for your own project. What do you think about the things mentioned above, or is there anything else you think is necessary for a README? Leave a comment below!

This article was translated from x-team and modified to fit the readers.