TRG 1.01 - README.md
Status | Created | Post-History |
---|---|---|
Update | 06-Dec-2023 | add detailed information for README file |
Active | 07-Mar-2023 | |
Draft | 13-Sept-2022 |
Why
A good README.md
file is the starting point for everyone opening your repository. It should help them find all critical information in an easy way.
A well-maintained README.md
shows the high level of professionalism of the project. It demonstrates that the developers care about user experience and want to make it easy for others to understand and use their work.
Description
Each repository must contain a README.md
file which shall cover following topics:
- Basic documentation of the repository, its content and its structure
- Installation instructions
- If required necessary step(s) to finish the installation
- Usage examples and intended use of your product
- License information
- Troubleshooting and FAQs to help users solve common problems
- Reference your Contribution guideline in the
CONTRIBUTING.md
file - Contact information to help users getting in touch with you
- Badges to show the status of your project (e.g. build status, code coverage, etc.)
Best practices:
- If installation instructions for your product are too complex being part of
README.md
move its content to a separateINSTALL.md
file, see TRG 1.02. - If your project is too complex to be described in a single
README.md
file, it may be beneficial to relocate specific sections to a dedicateddocs/
folder. - If your project has multiple component repositories (e.g. frontend and backend), link the other repositories in your leading repository in your
README.md
mutually.
In summary, a good README is a crucial component of any repository, serving as a gateway for users and contributors to understand, use, and potentially contribute to your project. It's a fundamental part of effective project communication and collaboration.
Further example on how to create your README.md
file.