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:
