Getting AI to Write Your README — Extract, Don't Generate

Ask an AI to "write the docs for this repo" and you'll usually get back something plausible and half-wrong: functions that don't exist, flows that don't match reality, a module you deleted three months ago. And honestly? That's not really the model's fault — it's how you asked.

I work on a US consumer-fintech backend running on Firebase Cloud Functions — payments, cards, fraud detection, ledger, a handful of external processors, a few hundred files. Onboarding is rough, and how good the docs are pretty much decides how fast a new engineer gets up to speed. After running "let the AI write the docs" a bunch of times, the line between what works and what flops got really clear. It all comes down to one flip: stop asking it to write, start asking it to extract. That's the whole trick.

1. Lock down the reader and the goal first

Biggest lever, by a mile. Before you generate anything, figure out in one sentence who's reading this and why, and hand that to the model.

• ✗ "Write documentation for this codebase."
• ✓ "Write a map that lets an engineer tracing a webhook for the first time follow the path from signature verification to ledger update in 15 minutes."

Change the reader and you get a totally different doc. Docs for an auditor, for an on-call responder, and for a dev adding a feature are three different things — same system, completely different write-ups. Leave it vague and the AI hands you a generic everything-blob that helps nobody.

2. Granularity — make it write a map, not an encyclopedia

Left alone, AI wants to write the giant covers-everything doc. Total trap. The longer it gets, the more lies sneak in — and the faster the whole thing rots.

The single most useful doc we've got? Not even prose — it's just a navigation map. Looks roughly like this:

functions/src/
├── index.ts         # START HERE — every endpoint export
├── coreTransaction/ # transaction processing
├── fraud/           # fraud detection
└── ...
How to trace: find the function in index.ts → follow imports into each dir

"Start at index.ts and follow the imports" — that one line is what lets a newcomer go read the code on their own. So don't make the AI explain everything; make it point at where to look. Keep the deep stuff short and right next to the code it describes, and just link to it from the map. Maps rot slowly; details stay in sync when they live beside the code.

3. Extract facts from the code that actually exists

This is the heart of hallucination control: don't let the AI imagine what should be there — make it read what is there and summarize. That's it.

• Start it from the files where the facts actually live (index.ts, the directory tree).
• Tell it: "Read these files and list only the exports that actually exist."
• Don't let it make up behavior. If a comment and the code disagree, have it write "unclear" instead of guessing.

Our code has hard rules — money's stored as integer cents, never floats; existing Firestore docs always get written with { merge: true }. Let an AI invent rules like these and it'll get them subtly, confidently wrong. Real conventions get written down once by a human, and the AI just references them. Splitting generate from reference is the move.

4. Keep it next to the code so it can't rot

The number-one reason docs go stale? "Written once, far from the code, then forgotten." So:

• Keep docs in the repo — don't banish them to some separate wiki.
• Make "update this doc when the code changes" a routine task, and have the AI draft the update straight from the diff.
• Even once a month, run a "diff the doc against the code and flag what's stale" pass.

Writing docs in a form you can actually keep updating — instead of "write once and ship" — is the whole difference between AI docs that help and AI docs that mislead.

5. Verify — make it cite file:line, then spot-check

Always do this last bit. AI lies with a completely straight face, so never take the output at face value.

• Make every claim come with a file and line number ("this function lives at coreLedger.ts:142").
• Actually open 3–5 at random and check them against the code.
• If even one's wrong, stop trusting that whole section and regenerate it.

Just forcing citations cuts the confident-fabrication rate way down. And verifying stays cheap — you sample, you don't re-read the whole thing.

Takeaway

Getting good docs out of an AI basically comes down to asking a good question:

1. Pin the reader and goal in one sentence before you start.
2. Make it write a map, not an encyclopedia.
3. Extract from code that exists, not code that "should."
4. Keep it next to the code and keep updating it.
5. Spot-check via file:line citations.

The second you toss it "write the docs," you've already lost. Don't use AI as an author — use it as a ridiculously fast extractor.