Writing Your Documentation: Letting AI Draft the Docs So You Can Decide What’s Worth Explaining

You’ve built something and you know you should write it down. The code works, but six months from now, or the day someone else opens the project, all the reasoning that’s currently living in your head is going to be gone. So you do the responsible thing: you ask your AI assistant to document the codebase. Say you’re building a tool that lets small law firms track billable hours. A minute later you’ve got documentation everywhere. Every function has a comment explaining what it does, every file has a header, there’s a README that walks through the folder structure, a description of each module, a note on every parameter. It’s thorough. It reads like a real project maintained by real professionals. You feel like you finally did the thing you always skip.

And that wall of documentation is quietly useless in a specific way. AI documented what the code says, because that’s what it can see. It wrote a comment on the function that calculates a bill saying “this function calculates the bill,” which anyone reading the function already knew. What it didn’t write, because it couldn’t, is the thing you actually need documented: why the billing rounds up to the nearest six minutes even though that looks like a bug, that the rounding is a legal convention in your clients’ world and someone will “fix” it and cause a disaster if it isn’t written down. The docs describe every obvious thing and none of the surprising ones. The careless version of this job isn’t asking AI to write documentation. It’s letting AI document what’s visible and calling it done, so you end up with a pile of text that restates the code and never captures the reasoning that was the whole reason to write anything down.

What this job actually is

Documenting your project is two jobs that get crushed into one word. The first is the writing itself: taking something that should be explained and turning it into clear, well-organized, readable prose. Formatting the README, structuring the sections, describing the setup steps, writing the sentences so they’re actually legible. That’s a generation-and-craft problem, and AI is genuinely good at it. It writes clean, patient explanations faster than you will, it never gets bored halfway through, and it’ll format the whole thing consistently without you having to think about it.

The second job is deciding what actually needs explaining. Out of everything in your project, what would a future reader (including future-you, who will remember nothing) genuinely be confused by or trip over? Which decisions look wrong but aren’t? Which parts are surprising, non-obvious, or load-bearing in a way the code itself doesn’t reveal? And which of the thousand things you could document are so obvious that writing them down just buries the useful stuff in noise? That’s not a writing problem. It’s a judgment call about what’s actually surprising in your specific project, and it depends on what only you currently know.

Here’s the distinction that matters: AI can generate the documentation, but deciding what’s worth documenting is yours. More documentation is not better documentation. The value of docs comes entirely from capturing the things a reader can’t figure out on their own, and that means knowing which parts of your project would surprise someone. AI can’t know that, because it can only see what the code does, not why you made it do that, or which of your choices will look like mistakes to someone who wasn’t there. It’ll document the obvious and the surprising at exactly the same depth, and leave the one comment that would have saved someone a day buried under fifty that saved no one anything.

How to delegate the writing

So lean on AI for the part it’s good at, which is turning things-worth-explaining into clear, organized prose. The move that makes this delegation work is bringing the substance yourself and letting AI do the writing, instead of AI both deciding what to say and saying it while you skim the result.

The careless version is “document my codebase,” which produces the comment-on-everything result, because with nothing told to it about what’s surprising, AI does the only thing it can and describes what it sees. The good version starts with you naming the non-obvious things. Tell AI the decisions that look strange but are deliberate, the constraints that aren’t visible in the code, the gotchas that will bite someone, the reasoning behind the choices a reader would question. Then hand AI that raw material and ask it to turn it into clear documentation: write it up readably, organize it sensibly, put the surprising things where someone would actually look for them, and write the setup and usage instructions so a newcomer can get the project running without you.

Ask AI to do the genuinely useful mechanical parts too: draft the README structure, write the getting-started steps, describe how the pieces fit together at a high level, format everything consistently. That scaffolding is real work and AI does it well. You can even let it write the routine reference material, the “here’s what this module broadly does,” as long as you’re clear that the reference layer is the floor and the reasoning you fed it is the part that matters.

What you don’t do is ask AI to decide what’s important and comment accordingly. The moment you leave that open, you get the even blanket of obvious notes, because AI had no way to know which three things were worth a paragraph and which fifty weren’t worth a line. Keep the ask on writing and organizing. Here are the surprising, non-obvious things a reader needs to know; write them up clearly and put them where they’ll be found, and scaffold the standard stuff around them. You hand AI the substance and the craft; you keep the choice of what substance there is.

The judgment you keep

Deciding what’s worth documenting is the call, and it’s yours because it turns on something AI can’t see: which parts of your project would actually surprise or mislead someone who wasn’t in your head when you built it.

This is hard because almost everything looks documentable in the abstract. Every function could have a comment; every file could have a header; more explanation always feels more responsible than less. But documentation has a cost that isn’t obvious: every line of it is a line someone has to read, and every obvious note you add makes the surprising note harder to find. Documentation that explains everything is nearly as useless as documentation that explains nothing, because the signal drowns. The judgment is in deciding that this specific thing, the six-minute billing rounding that looks like a bug and isn’t, absolutely has to be written down and written down loudly, while the function that adds two numbers needs no comment at all. For the law-firm app, the reasoning behind the rounding is worth a whole paragraph because someone will otherwise “fix” it into a lawsuit, while the code that formats a date is self-explanatory and documenting it just adds noise.

AI can’t make this call because it doesn’t know what’s surprising in your world. It can read what the code does, but it can’t know that a particular choice violates a reader’s expectations, or that a certain constant is a legal requirement rather than an arbitrary number, or that a weird-looking workaround is load-bearing, because all of that lives in context AI never had. Get this wrong and you land in the worst documentation spot there is: a thorough-looking set of docs that gives everyone false confidence, where the reader trusts it’s complete, skims the obvious notes, and walks straight into the one gotcha nobody wrote down because it was too obvious to you to seem worth saying. Knowing which things are surprising to someone who isn’t you is the entire point, and it’s the one part AI can’t hand you.

Before you ship this job

Here’s what good delegation looks like, and the line it can’t cross.

The sample prompt. Something real you might send:

I’m building BillTick, an app that helps small law firms track billable hours and generate invoices. My main user is someone like Theo, a solo attorney who bills dozens of clients and can’t afford invoicing mistakes. I’m going to give you the non-obvious things about this project that a future developer (or future-me) would trip on, and I want you to turn them into clear documentation and put each one where someone would actually look for it. Here they are: (1) billable time rounds up to the nearest six-minute increment because that’s a standard legal billing convention, not a bug, and it must never be “simplified” away; (2) the invoice total is intentionally recalculated from scratch every time rather than cached, because a stale cached total once caused a billing error and we decided correctness beats performance here; (3) the “archived” client status still counts toward monthly totals on purpose, for tax reasons. Write these up clearly and prominently. Then scaffold the standard stuff around them: a README with setup and getting-started steps, a high-level description of how the main pieces fit together, and consistent formatting throughout. Don’t add a comment to every function or document the self-explanatory parts; keep the obvious stuff out of the way so the surprising things stay findable.

Use this and you get docs that capture what a reader can’t figure out alone. Copy it as-is and you’re documenting BillTick’s surprises instead of your own. Theo’s gotchas are a law firm’s gotchas, the six-minute rounding and the tax-driven archiving; your project’s non-obvious things are somewhere else entirely, and the docs only earn their keep when they hold the reasoning that lives in your head and nobody else’s.

The part you can’t hand off is the selection: which decisions, constraints, and gotchas are surprising enough to be worth explaining, sorted out from the obvious things whose documentation would only bury the signal, judged against what a reader who wasn’t there would actually trip on.

How to check AI did its part: find the single most surprising thing in your whole project, the decision most likely to make a new developer say “wait, why is it done this way,” and check whether the docs explain it, clearly, somewhere a confused person would actually look. Then do the reverse: skim the docs for comments that just restate what the code plainly says, the “this function returns the user” notes, and notice how much of the documentation is that. If the one genuinely surprising thing is missing or buried while the obvious notes pile up, the docs are describing the code instead of explaining the project, no matter how complete they look. The test isn’t how much got documented; it’s whether the thing a reader would actually get wrong is the thing that got explained best.

What you get for doing it this way

Go back to that thorough-looking pile of comments, the one that restated every function and captured nothing. The difference between letting AI document what it sees and directing it to document what’s surprising is the difference between docs that describe your code and docs that actually save someone from the mistake you can see coming. When you bring the reasoning and let AI write it up well, the person who opens your project in six months (quite possibly you) finds the gotcha explained right where they’d hit it, understands the choice that looked wrong, and doesn’t “fix” the thing that was never broken.

AI can write clear, organized, thorough documentation faster than you ever would. Which things are actually worth documenting, the surprises only you currently know about, was always going to be your call, because only you know what a reader who wasn’t there would get wrong. That’s the job: let AI draft the docs, then decide for yourself what’s actually worth explaining.