How to write a good README for your project

A good README.md is essential for any project. It is a summary of your project and gives users instructions & important information. This is a simple guide to help you make an accessible guide for your project.

What is a README?

A README is a file that explains the details and all important information for a project. A standard README file will have a .md (Markdown) extension and will be at the root of your project repo. Note: Get used to typing in the Markdown Language for your project README's! There is still a lot of different styling & editing options available in markdown vs .docx, .txt. etc.

The Structure of a README

Example of a Good README

1. Project Title
   This is the must have of any project. It is important to know what your project is going to be about and the title represents that.

2. Project Description
   This is an important part of your project and what many developers and non-developers will look at. It is vital to have the most accurate and correct information. The description needs to be well written with no grammar errors and that is readable to users of multiple backgrounds. It is important to put some time and thought into writing the description of the project. It does not need to be long but needs to summarize the project. (What does your app do? What tech did you use?)

3. Table of Contents (Optional)
   A table of contents is good if you have a lengthy README and can help users navigate to sections quickly but is not a must have.

4. Getting Started
   This section typically is brief and will list the pre-requisites that the user must have in order to start using the project code. This section can be similar or be combined with the Installation section. (Ex: Must have node -v)

5. Installation
   This is where you will list the full instructions for users on how they can install and start using your project. This should include multiple steps and have detailed descriptions and outcomes for users. It is important to take your time and write these steps as thoroughly as possible. This will help users a lot and will help prevent users from coming back and asking follow-up questions.

6. Other Instructions, Specifications, Attributes, or Project Info
   This section(s) can include any other relevant project information. This can include information specific to a particular OS or Framework (Ex: Linux, React, etc). Certain projects have specific instructions and information that may need to have their own separate sections. As you develop your project you will get a better idea of what you need to include in your README and how to structure it.

7. Contributing
   It is important to list all the names and information of the people who've contributed to the project. Be sure to include their GitHub Profile Name and any other social media they may want to have listed. There are some cool markdown contributing badges that I will list in the Good Resources below.

8. Acknowledgements
   Similar to Contributing it is important to include all the sources that helped you complete this project. It's always good to give credit where credit is due.

9. License
   Choose a license for your project. To learn more about license's check out choosealicense.com.

✧ Optional: Additional Sections

• How to Contribute to the Project
  Add ways that that developers can contribute to the project.

• Tests
  Write tests for your application and then provide examples on how to run them.

• Examples
  You really go the extra mile when you provide examples of your code/application. This could be a screenshot, code block, video, webpage, etc. This can be really helpful to your users.

• Badges
  Try adding some cool markdown badges! There are badges at sites like shields.io and they include important code monitoring and other tracking info. Check out the Good Resources section below.

Example of a Good README

Good Resources

• Make a readme the basics of a readme.
• Awesome Open Source has some great README templates.
• CLI readme generator a command line package.json & git config file.
• Shields.io badges for all your markdown documents.
• Badges Generator create your own markdown badges.
• Contributing Badge a contributing badge for your project README.
• choosealicense.com information for license's for projects.
• Open Source License Article information on open source license's.

👋 Thanks so much for reading this article! Please check out my other articles on Dev.to and connect with me on LinkedIn.

Kendra WingFollow

Developer & Advocate. I Build Creative UI & Innovative Apps with React.js, APIs, SQL, JS Frameworks, Open Source, & LLMs / AI 🔮.