Skip to main content

TRG 1.01 - README.md

StatusCreatedPost-History
Update06-Dec-2023add detailed information for README file
Active07-Mar-2023
Draft13-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 separate INSTALL.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 dedicated docs/ 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.