Treat AI-Generated READMEs Like First Drafts

Your AI Wrote the README. Now Get Out the Red Pen.Ask AI to "write a README for this repository," and you shall receive.If you're careful, you might give it a template. Maybe you've baked documentation requirements into a spec-driven workflow. Either way, what comes back usually looks polished enough to trust: neat sections, clean Markdown, sensible links, maybe even enough technical detail that you start noticing things about your own project you hadn't thought to document yourself.It's awesome.You didn't have to do the tedious work of gathering what you know, deciding what matters, organizing it for someone else, and turning all of that into what will probably become the single most referenced piece of documentation in your repository.The model handled the formatting. It picked the headings. It linked the sections. It may even have sprinkled in an emoji or two with unnerving confidence.And that's exactly when I think you should get out the red pen.I have a B.A. in English, so apparently this was inevitable.Because the problem with an AI-generated README usually isn't that it looks bad. It's that it can look finished before anyone has actually edited it.A README can be technically correct, impressively thorough, and still make a human reader work much harder than they should.The dangerous README isn't the obviously bad one. It's the one that looks finished.So I graded mine like a paperI recently had AI generate documentation for a small local job-search system I'd been working on. The project takes a resume and uses local models to do things like generate interview-prep questions, compare the resume against a specific job description, and rank multiple postings by fit.The generated README was thorough.Really thorough.It documented the setup, individual scripts, command-line flags, matching logic, caching, token tracking, implementation details, limitations and basically every other piece of the project it could get its hands on.At first glance, that sounds like exactly what I asked for.But instead of asking another model to "improve the README," I decided to do something considerably less sophisticated.I read it. Then I started writing on it in red pen.All four are builtThe README says "All four are built" as a status update on a four-step workflowThe README opens by describing the project as a four-step progression and then announces:"All four are built."There's nothing factually wrong with that sentence. My red-pen reaction was: who is this update for?"All four are built" makes perfect sense from the perspective of someone who has been following the development of the project. It sounds like a status update.But someone landing on the repository for the first time doesn't care what I finished. They want to know what they can do.That's an editorial distinction.Something like "The system includes four tools for different stages of interview preparation" puts the reader back at the center without changing the underlying information.The AI successfully documented the project.The editor still had to ask who the documentation was for.Wait. Where did my job description go?Then I got to the instructions for adding a job posting.Clipboard instructions with "WHERE DID THE DESCRIPTION GO??"The workflow tells the user to select a job description, hit Cmd-C, and then run:python rank_postings.py --add "Acme — Senior DevRel" There is one conspicuous thing missing from that command. The job description I just copied.It turns out the command reads the clipboard automatically. The text in quotes is just the label used to identify the posting. The README eventually explains this behavior, but the actual interaction asks the reader to make a cognitive leap: I copied something, ran a command that doesn't contain it, and I am supposed to understand that the program grabbed it from somewhere else.The code may work perfectly.The instructions may even be technically accurate.But technical accuracy and usable instructions are not the same thing.The fix is almost comically small:"Copy the job description to your clipboard. Then run the following command. --add reads the job description directly from your clipboard."That's it.AI knew what the command did. What it didn't do particularly well was recognize the moment when a human would ask, "Wait, what just happened?"And that's exactly the kind of question an editor is supposed to ask.Cool. Why do I need to know this right now?Then there was this.CPU/MPS paragraph with red markupRight in the setup section, after explaining how to install and run the project, the README gives me this useful little nugget: the embedding step is forced onto the CPU because, on the machine the project was built on, PyTorch's Apple MPS backend had silently returned ~1.0 embeddings under memory pressure.That's genuinely useful information!I would absolutely want it documented.I just don't know why I need to know it right now.At this point I'm still trying to get the thing running.This is where AI-generated documentation can become almost paradoxically too good at documenting. If the information exists and appears relevant, the model has every incentive to explain it. The result can be comprehensive documentation with terrible information hierarchy.A human editor has to make a different decision:Not "Is this useful?" but "When is this useful?"That paragraph probably belongs in troubleshooting, implementation notes, or developer documentation.Deleting it would make the documentation less complete.Moving it would make the documentation better.And sometimes the red pen says KEEP THISSome of the generated documentation was really good."What's deferred" with KEEP THISThe README includes an entire section explaining what the tool doesn't do and where its results can be unreliable.It tells the reader that vague inputs produce vague outputs. It explicitly says URL fetching only supports Greenhouse and Lever. It explains that ranking treats all requirements equally and that fuzzy matching can cause a real gap to appear as a partial match. It calls out limitations in salary parsing and location matching.My editorial contribution to that section?KEEP THIS.That's useful documentation.It helps someone understand not only how to operate the software, but how much confidence to place in what comes out of it.And I think that's important to the larger point.The red pen isn't there because AI can't write.It's there because writing was never the last step. Editing is.Generation and editing are different jobsWhen I ask a model to document a repository, I'm asking it to synthesize an enormous amount of information.That is something LLMs are remarkably useful for.They can inspect files, follow relationships between components, identify configuration options, explain commands, organize information, produce Markdown, and turn implementation details into prose much faster than I could starting from a blank page.I have absolutely no desire to give that up.But generating all of the relevant information and deciding how another human should encounter that information are different jobs. The second one runs on a different set of questions entirely.Those aren't Markdown problems.They're editorial problems.And they're surprisingly easy to miss when the first draft arrives already formatted like finished documentation.Don't just ask another AI if the README is goodThere's another tempting solution here: generate the README with one model, then hand it to another model and ask for a critique.That's useful. I do it.But I wouldn't make that the final gate either.A second model can catch contradictions, missing information, confusing wording, broken links, questionable assumptions and plenty of other things that are difficult to spot when you've been staring at the same project for hours.Use it.Run the commands too.Click the links.Follow the setup instructions from a clean environment if you can.And then read the thing like someone who wasn't there when you built it.For me, that means mentally pulling out the same red pen I once used on essays.The questions aren't actually that different:Who is the audience?Why is this paragraph here?Did you explain that before referring to it?Does the conclusion follow from what came before?Is this information necessary?Are you making the reader do work that the writer should have done?Apparently my English degree was preparing me for AI-assisted software development all along.The README is part of the productAI has made it absurdly easy to produce documentation that looks complete.That's a good thing.I can spend less time manually inventorying every flag, function and dependency in a repository and more time deciding how those pieces should be explained.But that's also why I don't think "write the README" should be the last prompt in a coding session.Treat the output like a first draft.Test it against the actual software. Check the claims. Follow the instructions. Move things around. Delete the development diary that accidentally wandered into the user guide. Keep the weirdly specific limitation that will save somebody an hour six months from now.And every once in a while, get out the red pen.Your AI can write the README.Someone still has to edit it.