DEV Community

Oumayma JavaScript Developer
Oumayma JavaScript Developer

Posted on • Updated on

What should be in a readme file?

A readme file is the first file a person will see when they encounter your project, so it should be briefly detailed and pretty. It gives the user (who visits your repository) a brief idea about what the project is about, what your project can do, how to run it, etc.

As projects vary, we can establish that there's no one right way to structure a good README. But there is one very wrong way, and that is to not include a README at all.

It is also important to note that when you're writing your project's README, it should be able to answer the what, why, and the how of the project.

Here you will find the basic information to add to your readme file.

Title

This is the name of the project. It describes the whole project in one sentence and helps people understand what the main goal and aim of the project are.

Description

A good description should mention:

  • The purpose of your application
  • Links to other projects that this application might be linked to.
  • Technologies used.

How to Install and Run the Project Locally

Include the steps required to install your project and also the required dependencies if any.

Provide a step-by-step description of how to get the development environment running.

If possible provide steps to run the projects in containers including the commands used.

Provide Relevant Links

Provide a link to the application or documentation such as swagger in case of a web application of an API.

Wrap-up!

There you have it, few steps to get you started with writing your first readme file.
For more details on how to write one, here's a good link to get started.

Top comments (1)

Collapse
 
caiovinicius42 profile image
Caio Vinicius

Thank you for good post.