92 lines
2.9 KiB
Markdown
92 lines
2.9 KiB
Markdown
|
## FreeCodeCamp - my favorite resource
|
||
|
|
|
||
|
|
[How to Write a Good README File for Your GitHub Project](https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/)
|
||
|
|
|
||
|
|
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](https://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](https://www.contributor-covenant.org/)
|
||
|
|
and the [Contributing guide](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
|
||
|
|
|
||
|
|
- **Include Tests**
|
||
|
|
|
||
|
|
provide code examples and how to run them
|
||
|
|
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Readme Generators
|
||
|
|
|
||
|
|
- [Make a README](https://www.makeareadme.com/)
|
||
|
|
- [README Generator](https://rahuldkjain.github.io/gh-profile-readme-generator/)
|
||
|
|
- [README](https://github.com/kefranabg/readme-md-generator)
|