Stop Letting Your Model Write the README

If you only change one thing about how you work with an LLM this year, make it this: never let the model write your READMEs, docstrings, or comments. I mean that literally. Generate the code, generate the scaffolding, generate the test fixtures you were dreading. But the prose that explains why any of it exists? That’s yours.

I’ve been building bots long enough to have opinions about this, and I came to the rule independently before seeing other developers land in the same place. The “2x, not 10x” crowd writing about coding with LLMs in 2026 puts it about as plainly as I would. Write your own docs. And yes, they really mean it.

Why generated documentation quietly rots your project

The models are good now. GPT-6 can hold tens of thousands of words together coherently, which is a wild jump from the early GPT-1 days when output fell apart after a few sentences. MiniMax M3 is in the same conversation. Coherence isn’t the problem anymore.

The problem is that documentation isn’t a summary of code. It’s a record of decisions. When I write a README for a bot, I’m encoding things that exist nowhere in the source: why I picked polling over webhooks, which API I gave up on after two days of rate limit pain, what the next person should not try. A model reading my repo can describe what the code does. It cannot tell you what I chose not to do, or why.

Generated comments are worse. They restate the line above them. // increment the counter sitting above counter++ is not documentation, it’s noise with good grammar. And because it looks like documentation, it discourages anyone from writing the real thing.

The asymmetry that makes this rule work

Code has a compiler and a test suite. If the model is wrong, something breaks and you find out. Documentation has no such check. A confidently wrong README ships, gets read, and misleads people for months. You carry all the risk and get almost no speed back, because writing a good README was never the slow part of your week.

Where the real gains actually live

Skipping code generation and going straight from a vague prompt to output is the common mistake. Addy Osmani describes his workflow starting somewhere else entirely: brainstorm a detailed specification with the AI first, then outline from there. That ordering matters more than any prompt trick.

My version of it, for bot work specifically:

• Write the spec in markdown yourself. Inputs, outputs, failure modes, what happens when the upstream API returns a 500 at 3am. Plain prose, no code.
• Feed the markdown back as context. Markdown turns out to be excellent LLM input. Instead of me manually checking every item on a list, I hand over the document and ask the model to verify the implementation covers it.
• Give examples, not adjectives. “Handle malformed payloads gracefully” produces vague code. Three sample payloads and the exact expected behavior for each produces code I can use.
• Generate in small pieces. One function, one handler, one test file. Large generations hide small mistakes in a wall of plausible text.
• Write the docs last, by hand. By then you actually understand the system, which is the only state in which good documentation gets written.

A realistic number

The honest framing is 2x, not 10x. I find that matches my experience building and shipping bots. The model removes the typing, the boilerplate, the fifteen minutes of looking up argument order in a library I use twice a year. It does not remove design work, and it does not remove the part where you read the output carefully enough to catch the subtly wrong thing.

Anyone promising an order of magnitude is measuring lines produced, not features shipped. Those are different metrics and only one of them pays.

The review habit that keeps this honest

Treat generated code the way you’d treat a pull request from a fast, confident contributor who has never seen your production environment. Read every line. Run it. Check the edge case it probably skipped. There’s a growing set of LLM evaluation tools in 2026 worth knowing if you’re shipping model-dependent features, but for plain code generation, the evaluation tool is you.

Use the model for the mechanical work. Keep the explaining for yourself. Your future teammates, including future you at 3am, will notice the difference immediately.

🕒 Published: September 18, 2026