Project Documentation: The README and Handover Minimum

Project documentation is the written material that lets someone else run, understand and change your code without you. Its foundation is the README.md file at the root of the repository: the first thing a developer opens, and often the only thing they read.

You don’t need extensive documentation. You need a minimum that answers a newcomer’s day-one questions. If the project was built by one person with an AI assistant, those answers usually exist only in that person’s head, until the first holiday, illness or change of contractor.

When it becomes urgent

Documentation gets postponed while you remember everything yourself. It becomes urgent in one of these situations:

• you hire your first developer or hand the project to an agency;
• the contractor who wrote everything leaves;
• an investor or acquirer runs technical due diligence;
• you come back to the project yourself after six months away.

In each case, a missing README costs days of someone else’s time. An agency will put those days on the invoice.

What goes in a README

The order of sections matters: from “what is this” to “how do I run it” and then into detail. A skeleton to start from:

README.md
  Name, plus two sentences: what it is and who it's for
  Running locally
  Environment variables
  How it works
  Deployment
  Gotchas
  Access and contacts

Here’s what to write in each.

Running locally

Step-by-step instructions from a clean machine to a running app. Language and package manager versions, install commands, how to create the database and fill it with test data, which address to open in the browser. The test is simple: give the instructions to someone who has never seen the project and watch where they get stuck. Every place they get stuck is a missing step.

Environment variables

List every variable with a note on what it does and where to get a development value. The values themselves don’t go in the README; they go in a .env.example file with blank or test values. Secrets in documentation are as much a leak as secrets in code.

Mark which variables are required and which switch on optional features. “Without SMTP_HOST, emails are written to the log” is one line that saves an hour.

How it works

An architecture sketch, not a thesis. What the system is made of: frontend, backend, database, background jobs, external services. Where each part lives in the repository. How the main flow, payments for example, travels from button to database row.

Half a page of text or a simple diagram is enough. Most important is explaining decisions that look odd: “prices are stored in cents”, “this table is never deleted from, rows are flagged instead”, “this endpoint has no auth check on purpose, it’s public”. Without those notes, a newcomer will “fix” things that are working correctly.

Deployment

How code reaches production: automatically on merge to the main branch, or by hand, and with which command. Where the hosting is, where the database is, where the domain and DNS are managed. How to roll back to the previous version. How database migrations run and what to do if one fails.

If deploying involves a manual step only one person knows about, write that down first.

Gotchas

The most valuable section, and the one almost nobody writes. Everything you’ve tripped over yourself:

• functions that need extra care before touching;
• external services with rate limits or odd behaviour;
• known bugs and their workarounds;
• scheduled jobs running somewhere that are easy to forget.

Access and contacts

No passwords. Just a list: which services are used, whose account each one is under, who to ask for access. When handing a project to an agency, this becomes the checklist: has everything been handed over, has everything been moved to the company’s name.

Keeping project documentation from going stale

Keep it in the repository next to the code, not in a separate tool, so changes show up in the same commits. The rule is simple: if you change how the project runs or deploys, update the README in the same commit.

If you work with an AI assistant, it probably has its own instructions file (CLAUDE.md, .cursorrules or similar). The good news: what you write for the assistant is almost word for word useful to people. The bad news: if it’s only written there, a person won’t find it. Link one file from the other.

In short

• Project documentation starts with a README that gets the project running without its author.
• The minimum: setup, environment variables, an architecture sketch, deployment, gotchas, access.
• Secrets never go in docs, only variable names and a .env.example file.
• Explain the odd decisions, or someone will “fix” them.
• Update the README in the same commit as the change it describes.

SUBXCAT writes this kind of documentation as part of a project handover, so the next developer is productive on day one.