README

Why

README as the name implies is the first document that anyone would be asked to read before exploring the source code files. Most source control put README as the front page of a repository. It should tells what a repository is all about in a clear and instructive way.

Convention

  • It should contains an overview or general information about the project
  • It should contains Sonarqube badge: Quality Gates, Bug Count, Code Smells, Coverage, Reability, Security, Maintainability
  • It should contains technology used
  • It should contains setup instruction, most importantly development setup for other developer
  • Optionally contains screenshots or architectural diagram

Please see the template here.

Example

image