The README Nobody Reads Until Something Breaks

The README Nobody Reads Until Something Breaks

There are two kinds of README files. The first kind gets written before anyone uses the project — it's optimistic, it covers the happy path, it assumes the reader has the same context as the writer. The second kind gets written after something breaks — it's specific, it covers the edge cases, it assumes the reader is panicking at 2am and needs to know exactly what to do.

The second kind is the useful one. The problem is that it only gets written after the incident that made it necessary.

Why Documentation Gets Written Wrong

Documentation gets written wrong because it gets written by the person who built the thing, immediately after building it, when everything is obvious. The builder knows why the configuration file has to be in that specific directory. The builder knows why you have to run the migration before the seed. The builder knows which environment variable is actually required versus which ones have defaults.

None of that knowledge makes it into the README, because the builder doesn't know they know it. It's tacit knowledge — the kind that only becomes visible when someone who doesn't have it tries to use the thing and fails.

The opened terminal has been thinking about this for a while. The gap between what the builder knows and what the README says is the gap where incidents live.

The Post-Mortem README

The best documentation I've ever read was written in the aftermath of a production incident. Someone had spent six hours debugging a problem that turned out to be a missing environment variable that wasn't documented anywhere. They were furious. They wrote the most detailed, specific, accurate README section I've ever seen. It covered every possible way that particular configuration could go wrong, with exact error messages and exact solutions.

That section has saved probably a hundred hours of debugging since then. The incident that produced it cost six hours. The ROI is obvious. The problem is that you can't write that section without the incident.

Or can you? The calitoycore approach to this is to treat documentation as a test. Before you ship, ask: what would a new person need to know to run this from scratch? Then try to run it from scratch, following only the README. Every place you have to deviate from the README is a place the README is wrong.

The Archaeology Problem

Old projects have a different documentation problem. The README was written years ago, by someone who may not be around anymore, for a version of the project that no longer exists. The documentation is accurate for a past state of the system. The system has moved on. The documentation hasn't.

The tarosyn dev log has been dealing with this — a project that's evolved significantly from its initial design, with documentation that still describes the initial design. The gap between the docs and the reality is a source of constant confusion for new contributors.

The solution is to treat documentation as code — version it, review it, update it when the system changes. This is obvious in theory and almost never done in practice, because documentation updates don't feel as urgent as feature work until something breaks.

The README That Actually Gets Read

The README that actually gets read is the one that's short, specific, and assumes the reader is in trouble. It answers: how do I run this? What can go wrong? What do I do when it goes wrong? Everything else is secondary.

The josephcalitoy.com essays have a useful frame for this: write for the person who needs it most, not the person who needs it least. The person who needs the README most is the person who's never seen the project before and something is broken. Write for them.