Most documentation is written once, goes stale within a month, and misleads people afterwards. Wrong documentation is worse than none, because people trust it. So write only the parts that earn their maintenance.

1. How to run it

From a clean clone, every command in order, including the prerequisites and the environment variables. This is the highest-value document you can write and the one most often missing.

Test it by following it yourself on a fresh checkout. You will find at least one step you'd forgotten was necessary.

2. Why, not what

Code says what it does. It cannot say why you chose this approach, what you tried that didn't work, or what constraint forced an odd decision.

That's what comments and decision records are for. // this must run before the auth middleware, or the preflight is rejected is worth more than twenty comments describing what the next line does.

3. The things that would surprise someone

Every project has them. The service that must be started first. The environment variable with a non-obvious name. The test that fails on the first run and passes after. The file you must not edit because it's generated.

Nobody can infer these. Write them down.

What to skip

Descriptions of what functions do, when the name already says it. Architecture diagrams that go stale in a fortnight. Anything auto-generated that nobody reads. A contributing guide for a solo project.

write-docs.txt
Here's my project: <paste the file list and key files>

Write a README with exactly these sections:
1. What this is, two sentences.
2. Running it locally — every command from a clean clone.
3. Environment variables, with what each is for.
4. Deploying it.
5. Three things a newcomer would get wrong.

No badges, no table of contents, no contribution boilerplate.

For section 5, tell me what you had to work out that wasn't obvious
from reading the code — that's exactly what I need to document.

Keep it next to the code

Documentation in a separate wiki goes stale because updating it is a separate task. In the repository, in the same commit as the change, it has a chance.

The best test of documentation is handing it to someone and saying nothing. Everywhere they get stuck is a gap; everywhere they ask you is a line you should have written.