CodeNewbie Community 🌱

Cover image for How to write a good README for your project
Kendra Wing
Kendra Wing

Posted on

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


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


This article was originally published on Dev.to on March 23, 2022, by @kwing25.

Latest comments (3)

Collapse
 
joedavis77 profile image
joedavis77

This is a great example of what a README should look like. It provides a quick overview of the features and how to get started writing.

A great README is worth a thousand lines of code! It is the first thing visitors see about your project and can determine whether or not the viewer will give your project a chance.

Collapse
 
nickytonline profile image
Nick Taylor

Great stuff! Thanks for sharing. There’s also readme.so from Katherine Peterson for folks looking for readme templates.

Looking forward to your next post!