A project readme serves as getting started documentation for two types of user, the consumers of the project and the developers that contribute to the project. It is not intended to be exhaustive documentation for the entire project rather it needs to provide enough information to allow the audience to pursue their goal when encountering the project for the first time or after a prelonged absense from the project.

A readme should cover the following areas in the following order:

  • Description
  • Project status
  • Usage examples
  • User/API documentation ( This may be a link to an external document )
  • Installation instruction
  • How to report an issue
  • Motivations
  • Build instructions
    • Dependencies
    • How to build the project
    • How to run the tests
    • How to deploy and run the project
  • Contibuting instructions ( This may be a link to an external document )
    • Folder organisation
    • Design decisions
      • What constitutes a design decision, i.e. what stuff needs a wider approval
      • How are design decisions documented and approved e.g. via Architecture Decision Records
    • Making a change
      • Documentation expectations
      • Branching strategy
      • Coding style/expectations/architecture
      • Test strategy, what type of tests are expected to accompany each change
      • Commiting,
        • when can you commit e.g. what requirements you need to have met before you can commit a change.
        • what information is expected in a commit message.
  • License

References