Documentation on a small project: what to write and what not to

Why it doesn't get written

Two honest explanations. First: it feels like everyone remembers anyway. Second: it isn't clear what to write, so people write either nothing or a restatement of the code.

Both end the same way. Three months later the author doesn't remember why something was done that way, and a new contributor spends a week on what could have been explained in twenty minutes.

What definitely to write

How to run it. The first and most necessary. What to install, which settings to set, which command starts it, how to check it works.

The quality test: someone who has never seen the project gets it running from this text alone, without questions. If they can't, the text is bad.

What it's for. Five sentences: what the project is, who for, what problem it solves. Without this a reader studies code without understanding intent.

Why it was done this way. The most valuable part and the rarest. Not "we use this storage engine" but "we chose it because we need text search, and we tried the other one and it didn't suit us because of this".

That is never visible from code. In six months nobody, including the author, will remember the reason — and the decision will either be broken or feared.

What not to write

A restatement of the code. "The function computes a sum, takes a list and returns a number." That's visible from the code, and it goes stale the moment the code changes.

A detailed description of every screen. Goes stale fastest of all.

Future plans in the documentation. That's what the task list is for. In documentation, plans linger for years and mislead.

A rule worth remembering

Stale documentation is worse than none. With none, a person goes and reads the code. With documentation that lies, they trust it and get it wrong.

The practical conclusion: write little and maintain it. Three accurate pages beat thirty of which half is obsolete.

Where to keep it

In the repository, next to the code. A main file at the root, plus a folder of decision notes if they accumulate.

The reason is simple: documentation kept elsewhere doesn't get updated. When it sits alongside and is edited by the same change as the code, its chances of survival are far better.

A decision note: a ten-line format

A useful habit is a short note for every substantial decision:

• What we decided.
• When.
• What problem we had.
• What else we considered.
• Why we chose this.
• What it costs us.

Ten lines, five minutes. A year later it's the most valuable text in the project.

The minimum for a two-person project

One file at the root: what the project is, how to run it, roughly how it's built, what was decided and why. One page.

Update it when the way to run it changes or a new substantial decision is made. No more often.

That's enough. And at interview, a repository with a clear description makes a stronger impression than one more half-finished feature.