In most common scenarios, README files can have one of the following layouts.

Basic

  • Introduction
  • Where to download?
  • License
  • Versioning scheme
  • Build instructions
  • Contributing guidelines
  • Credits

The basic layout might seems too much in the beginning, but I think this is quite essential and valuable information that each open source project could have.

Being able to scan through each of these sections saves a lot of time.

Extended

  • Basic +
  • What problem does the project address?
  • Who cares?
  • How does it work?

Including these additional sections in the README almost eliminates the need to write an introductory blog post about the project.

Mature

  • Extended +
  • Open source maturity level1
  • Documentation
  • Questions
  • Who uses it?
  • Additional resources

As the project becomes bigger and successful, these additional sections tend to minimize potential duplicate questions on Stack Overflow and questions as issues on GitHub.


1 The description for the maturity levels of open source code can be found here.