Readme Essentials

Jonah Williams ·

On recent projects I’ve been trying to practice a little bit of readme driven development and trying to demand that the project maintain a useful readme. Theoretically the contents of the readme are things the entire development team is familiar with. Capturing them in a readme has still proven to be a useful exercise which adds clarity to the project’s structure, reveals tricks known by only some developers, and has been a significant time saver when bringing new developers onto the project.

Each project has its own needs but I have found that they all benefit from instructions which allow other developers to get up to speed quickly. When I join a project as a developer or consider using a shared library, I should be able to answer at a glace:

  • What does this project do?
  • How can I see it work?
  • How do I run tests?
  • How do I install/deploy/release the project?
  • How should I submit contributions or report bugs?
  • How do I know what needs to be done?
  • What license is this offered under?

With those questions in mind I’ve started using the following as a template for my projects’ readme files:

What do your readmes look like?