triston-notes/+ Encounters/Readme Best Practices Tips.md
2023-10-21 18:52:54 -05:00

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)