DEV Community

Cover image for How to Write an Awesome Readme
Suraj Vishwakarma for Documatic

Posted on • Updated on

How to Write an Awesome Readme

Introduction

After the code, the readme is the most important thing to add to your project. Readme will be referred to as docs for small libraries and projects. It will reflect the project. For a beginner, forgetting to add Readme files to the project is standard. Even some developers add readme files that end up as bad because they give the least attention to it.

A good Readme will help other developers in understanding the project. They can use it as the original source of information for the project. A good readme must contain some of the points that we will discuss later.

So, today I am going to guide you on writing awesome Readme files for your project. In this article, I will discuss the following points:

  • What is a Readme file?
  • Things to include in your readme
  • Tools that you can use to write a Readme file

Now, let’s get started.

What is Readme?

A readme file is a text file that summarized the documentation of your project. It is often included in the root directory of a project, and it is typically written in plain text or Markdown format.

The purpose of it is to provide a quick overview of the project and help users understand what it does, how to set it up, and how to use it. It includes information about the project. The user of the project will first read this file to gain knowledge about your project. It became the face of your project.

Adding valuable information to this file is necessary. Depending on the readme file, the user will interact with the project accordingly. There are must-include things that you need to add to your readme file. Let’s look into that.

Readme file on GitHub

Things to include in your Readme

Title and sub-title

You need to add the title of the project at the top of the Readme. Along with that, you can add a subtitle that denotes the project in a sentence or two.

You should also add the logo of your project too if there is any.

Table of Content

I think this is a must-include section for a large readme file. This will help the user while navigating through different sections.

Description

In this section, you can elaborate more on the project features and ideas. Add one to two paragraphs about the project so that the user understands the meaning of the project.

You can also talk about your motive for the project.

Working of the project

A Step-by-step guide for the user about different features and how to use them. Add screenshots to better illustrate the work. You can add diagrams to show the architecture of the project. You can also add videos or gifs in this section.

You can mention the tech stack that you have used in the project. This will help the user to have a better understanding of the project.

Installation Guide

I step-by-step guide with screenshots and code to guide users in installing projects on their machines.

You can mention some pre-installed tools that might require for local installation. Provide all the commands and scripts for installing on the machine with screenshots and code. Add a screenshot of the running project.

Contributing Guidelines

If the project is open source, you can talk about guidelines for contributing. You can add any external files too.

In the contribution guidelines, mention things to consider before creating a pull request. Mention what kind of pull request you want.

License

Mention the license of the project. There are different licenses according to the customization that others can make to your project You can look at the GitHub license page for different licenses for your project.

One of the most used licenses for me is MIT. It permits users for commercial use, modification, distribution, and private use. Limit the user for any liability and warranty.

Tools that you can use

Let’s look into some tools that might help you in writing and structuring the readme.

readme.so

Our simple editor allows you to quickly add and customize all the sections you need for your project's readme

screenshot - readme.so editor

It is an editor that will help in writing better readme. There are various sections such as Project titles, badges, authors, contributing, and others with templates that you can import into the editor. The editor supports markdown which makes it easy to add your section to it.

You will not run out of sections to add to your readme as the editor has more than 35 sections. Also, you create your own sections for the editor.

Terraform docs

Generate Terraform modules documentation in various formats

screenshot - terraform docs

Terraform is an open-source infrastructure to code software. It follows strict guidelines for creating variable definitions, providers, and others. It has a sub-project called as terraform docs. If you use terraform infrastructure then you can use the terraform docs for creating docs/readme for your project.

You can export readme in various formats such as Markdown, AscciDoc, JSON, and others. It has support for CLI that makes it easy to automate documentation generation with GitHub Action.

Conclusion

Readme files are quite important for any project. As mentioned above, this will be the face of your project and potential users will read it. That’s why creating a good readme should be a priority after writing code. We have discussed a lot about writing a readme such as a readme introduction, things to include in the readme, and tools that you can use to create an awesome readme.

I hope the article has helped in understanding the value of a readme file. Along with that, How to write a better readme for your project. Thanks for reading the article.

Top comments (8)

Collapse
 
gtanyware profile image
Graham Trott

Absolutely. There are far too many projects without a scrap of documentation. It's not hard to offer even a brief description of what the project is about; just lazy and arrogant not to.

I'm retired now but one of the things that used to make me see red was the arch reply I got from some programmers - typically the cleverest ones - when asked for just a hint where to start:

"Read the code". (smirk)

I cannot politely express how infuriating this was, especially when the code in question had not a single comment anywhere, on the grounds that "documentation gets out of date".

Collapse
 
emasuriano profile image
Ema Suriano

Hey, fan of AI here! I recently learn that you can generate a very rich and handy readme using GPT-3 as well! Given the prompt of:

write me a readme for my open source project in github which is a library of react components that can be used in a backoffice. The project is called "test-name".

The result is:

# test-name

test-name is a library of React components that can be used in a backoffice application. It provides a set of reusable, well-tested components that can help you build your backoffice faster.

## Installation

To install test-name, use npm:

`npm install test-name`

or yarn 

`yarn add test-name`

## Usage

To use test-name in your React project, import the components you need from the package:

`import { Button } from 'test-name';`

Then, use the imported component in your JSX:

`<Button>Click me</Button>`

## Components

test-name includes the following components:

- Button
- Input
- Table

## Contributing

We welcome contributions to test-name! If you have an idea for a new component or a bug fix, please open an issue or a pull request.

## License

test-name is licensed under the MIT License. See [LICENSE](LICENSE) for more information.
Enter fullscreen mode Exit fullscreen mode
Collapse
 
surajondev profile image
Suraj Vishwakarma

That's super ❤️

Collapse
 
linuxwrangler profile image
linuxwrangler

How about "Requirements". I can't count the number of times I've seen a project or product that doesn't tell you that up front. If it runs on every OS without additional requirements. Great! Say so. If you need to have PostgreSQL 14+, Python 8.4+, 64GB of RAM on a Linux box, tell us up front. You'll save a lot of people a lot of time.

Collapse
 
surajondev profile image
Suraj Vishwakarma

That's also a valid points for native apps. Even sometimes for a web application.

Collapse
 
drogbut profile image
drogbut

Very good article, thank you. I enjoyed reading it but for a beginner like me, I would have liked to see these points:

1) I would have liked to see some examples of open-source projects that you find that the author has written a good readme.

2) The links to the references are also missing in your article. For example, for the different types of licenses, you should have added the reference link to the Github page to make it easier for the readers.

Anyway, very good article overall. Great job!

Collapse
 
surajondev profile image
Suraj Vishwakarma

Yep, that is also a great point to add to the readme. I am working on an article that reflects some great readme examples.

Collapse
 
devitorcruz profile image
DeVitor

That was a awesome text it's helped me a lot. I'm beginning on code and every information about the better way to create the project as more readable then possible is great!!