Jack Moore

Email: jack(at)jmoore53.com
Project Updates

A Good Readme

01 Dec 2019 » documentation, docs, readme, gitlab

A good README.md is crucial for any open source project. They are living documents that need to be kept up to date as the project matures and changes.

Bare Minimum

At the bare minimum, a readme should have:

  • Title and One Sentence Overview of the project
  • Setup (How to Setup)
  • Contributing (How to Contribute)
  • License
  • Contact

Getting Better

When I think of good a good readme, I think of a readme that has:

  • A purpose and overview for the project with some photos! (including where to learn more about the project)
  • How to develop and work on the project (development guides)
  • How to set up and run the project
  • The requirements for running the project
  • What the project is built with (eg. Rails, React, Mysql)
  • Contributing guidelines
  • Security
  • The team and developers
  • The Copyright License
  • (Dedication, optional)


Some good examples of decent readmes come from most major projects including:

  • TensorFlow - Somewhat Barebones: Gives the overview, setup, how to contribute, and guides at the bottom
  • Dependabot - Provides a Medium Sized Readme
  • Discourse - Provides almost a full length feature of the project and good documentation
© Jack Moore