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
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.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?)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.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)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.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.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.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.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.
This article was originally published on Dev.to on March 23, 2022, by @kwing25.
Top comments (3)
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!
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.
For Roblox enthusiasts looking to enhance their gameplay, Delta Executor has quickly risen to become a top choice for running scripts.