The README

The first thing users and other developers look at when first making contact with a repository is the README.md in the repository’s root directory. Its purpose is to give a concise but comprehensive introduction to the project. It should provide links to further (more detailed) documentation, websites or other background information. Depending on the relevant ecosystem, specific guides or templates for READMEs exist.

The following basic information must be provided:

  1. The project name
  2. A short but meaningful descriptive summary of the repository
  3. The maintenance status

The following questions must be answered:

  1. What does the software do?
  2. Who will use the software?
  3. What are alternatives to the software, and how do they differ?
  4. How can someone get started?
    • Requirements
    • Binary download location
    • Build instructions with dependencies
    • Installation instructions
    • Quick start examples
    • Link to full user documentation
  5. How can others join the development?
    • Coding styles used
    • API design
    • Toolchain and frameworks used
    • Community communication platforms
    • Link to developer documentation
    • Test suite details
    • Contribution guides
  6. Release details and versioning
  7. Who has contributed to the software?
  8. Which license is used? In most cases a link to the LICENSE.txt is sufficient.
  9. Who has to be acknowledged? I.e. who has played a significant role for the creating of the software? This can e.g. include funding, research communities, or co-workers that are not part of the project but have given advice and/or input to the development process.