The README as Thinking Tool

Nobody reads your README. This is almost certainly true. Your colleagues skim it when they first join the project and never look at it again. External contributors read the first paragraph and then go straight to the code. You yourself haven't read it since you wrote it.

The README Nobody Reads - image 1

Write it anyway. Not for them. For you.

What Writing the README Does

Writing a README forces you to explain your project to someone who doesn't know it. That person is, in a useful sense, you from six months ago. Or you from six months from now, when you've forgotten why you made the decisions you made.

The Opened Terminal principle here is that documentation is a form of thinking. When you can't explain something clearly in prose, it usually means you don't understand it clearly yet. The README that's hard to write is telling you something about the project.

The README Nobody Reads - image 2

I've started writing READMEs before I write code. Not always — sometimes the project is too exploratory, too uncertain. But for anything that's going to live for more than a few weeks, writing the README first forces me to answer questions I'd otherwise defer: What problem does this solve? Who is it for? What are the constraints? What did I decide not to do, and why?

The systems thinking that comes out of this process is different from the thinking that comes out of just writing code. Code is specific. Prose is general. The README lives at the level of intention, which is where most projects go wrong — not in the implementation, but in the unclear intention that the implementation is trying to serve.

The dev logs from any serious project will show the moment when the README stopped matching the code. That's usually the moment when the project started accumulating technical debt. Not because the code got worse, but because the intention got blurry.

Write the README. Nobody will read it. It will still be worth it. More on fringe thinking and builder culture.