2.9 KiB
FreeCodeCamp - my favorite resource
How to Write a Good README File for Your GitHub Project
A README, it should be able to answer the what, why, and the how of the project:
- What was your motivation?
- Why did you build this project?
- What problem does it solve?
- What did you learn?
- What makes your project stand out? If your project has a lot of features, consider adding a "Features" section and listing them here.
Include in ReadMe
-
Project's Title
Describe whole project in 1 summary sentence
-
Project Description
Take the opportunity to explain and showcase
- What your application does,
- Why you used the technologies you used,
- Some of the challenges you faced and features you hope to implement in the future.
-
Table of Contents (Optional)
Only really need ToC if ReadMe is really long
put at top of ReadMe for ease of use
-
How to Install and Run the Project
Provide a step-by-step description of how to get the development environment set and running.
Include any dependencies
-
How to Use the Project
Provide instructions and examples so users/contributors can use the project
If they encounter a problem, they can refer to these steps
Include screenshots, code snippets, …
If authentication is required, include details about that as well
-
Include Credits
list your collaborators/team members including links to GitHub and social
reference tutorials if used
-
Add a License
this is usually considered the last part
The most common one is the GPL License which allows other to make modification to your code and use it for commercial purposes
-
Badges
Badges aren't necessary, but using them is a simple way of letting other developers know that you know what you're doing
The good thing about this section is that it automatically updates it self
Check out the badges hosted by shields.io
-
How to Contribute to the Project
You will want to add guidelines to let them know how they can contribute to your project
make sure that the license you choose for an open-source projects is correct to avoid future conflicts
Some of the most common guidelines include the Contributor Covenant and the Contributing guide
-
Include Tests
provide code examples and how to run them