A missing README is rarely just missing documentation. It usually signals other things, too.

  1. A project that’s going to be difficult to set up. When I pull down a project without a README, I’m starting from zero. What kind of app is this? What backend, frontend, persistence layer, and dependencies are involved? Has it ever been set up on my operating system? Answering these becomes homework I didn’t ask for.
  2. A project whose purpose may not be clearly defined. What is this project? Why does it matter?
  3. Shaky domain language. What kind of users do we have (Customers and Employees, or Players and Coaches)? What can those users do? Without a README, this information is needlessly obscure.

What if we have great docs outside the repo? Better than nothing, but docs should live close to the code: a text file in the project. This lets documentation travel with the code, ties changes together via version control, and gives the repo a clear front page.

All of this for the cost of touching a README and a few minutes of initial writing.

Note: this was originally posted on LinkedIn.