I Write the README Before I Write a Single Line of Code

The first file I create in a new project is not a source file. It is a README. Before there is any code, I write down what the thing does, how someone would install it, and what the first three commands they would run look like.

I picked up this habit about five years ago after building an internal tool nobody used. It worked fine. It was also impossible to explain in under ten minutes, and nobody had ten minutes.

What goes into a first-draft README

My first draft is short, usually around 300 words. It has four parts.

• One sentence on what it is for. Not what it is. What it is for. "Lets claims adjusters re-run a calculation for a single policy without filing a ticket."
• Installation in three steps or fewer. If I cannot imagine it in three steps, that is a design problem, not a documentation problem.
• A realistic example. A real input and the real output someone would see.
• What it does not do. This section saves more arguments than anything else I write.

I write it as if the tool already exists and works perfectly. Then I read it out loud. Usually something sounds wrong.

The three ideas it killed

The first was a command-line tool for bulk updating policy records. When I wrote the example, I realized every real use case needed a confirmation step that showed what would change. That made it a web form, not a CLI. Two weeks of work saved.

The second was a shared library for date handling. My README's "what it does not do" section turned into a longer list than the "what it does" section. That was a sign the library was trying to be a thin wrapper over something that already worked. I dropped it.

The third was a service to sync agent data between two systems. The installation section needed credentials from three different teams. Writing that down made me go talk to those teams first. One of them was already building the same sync.

It makes code review easier too

When I open a pull request for the first version, the README is already there. Reviewers can read it first and then check whether the code does what the README promises. It turns a vague review into a checklist.

It also gives my manager something to read. She does not review code, but she reads READMEs, and she has caught scope problems in them that no engineer flagged.

The objection I always hear

People tell me the README will just go out of date. Sometimes it does. But a README that drifted is still better than none, and the drift is itself information. If the README says one thing and the code does another, someone made a decision without writing it down. That is worth knowing.

I am not precious about the format. Some of my first drafts are just bullet points in a text file. The point is to describe the tool from the outside before I get lost on the inside, where every decision feels obvious because I am the one making it.