Blog / Build with AI /
Using AI to document your code and processes
Nobody wants to write documentation. It’s the job that gets pushed to “later”, and later turns out to be the day someone leaves, a site breaks, or you return to your own project after three months and can’t remember why it works.
AI is genuinely useful here. Not because it knows your project, but because it’s patient, it’s quick, and a rough first draft is exactly what documentation needs to get started.
Here’s how I’d use it for both code and everyday processes, and where to be careful.
The golden rule
AI can describe what is in front of it. It can’t know why you did something, what you tried first, or what the business rule behind it is. So let it handle the what, and you add the why.
That’s the split throughout this post.
Documenting code
1. Explain it line by line
Paste a function or script and ask:
Explain what this code does in plain English, step by step. Then list anything that looks risky or unclear.
This is useful twice over: you learn what the code does, and you get raw material for comments. I wrote about the technique in how to ask AI to explain code line by line.
2. Write the comments
Add short comments to this code explaining each section. Don’t comment obvious lines. Keep each comment under 15 words.
The last two sentences matter. Without them, AI tends to comment everything, like // add 1 to counter, which clutters code without helping.
Then read the comments. If one is wrong, the code is probably doing something you didn’t expect, which is worth knowing.
3. Draft the README
A README is the front door to a project. Give the AI the project’s files or a summary, and ask:
Write a README for this project with these sections: what it does, how to install it, how to use it, settings, known limits. Use plain language and short steps. Where you’re unsure, write “TO CHECK” rather than guessing.
That last instruction is important. You want the AI to flag gaps, not fill them with confident-sounding inventions.
4. Document the settings and inputs
For tools with options, ask for a table: setting name, what it does, default value, example. Check the defaults against the real code. This is where AI most often gets details wrong.
5. Write a changelog
Paste your list of changes or commit messages and ask for a plain-English changelog grouped into “added”, “changed” and “fixed”. It’s a tidy way to keep users informed. A versioned history also helps you spot what changed when something breaks, as I described in the system I use for managing several websites.
Documenting processes
Code isn’t the only thing that needs writing down. For anyone running websites, the processes matter just as much: how to publish a post, how to renew a domain, how to restore a backup, what to do when checkout fails.
Turn messy notes into steps
The best use is to turn what’s in your head into clear steps. Talk or type your notes as they come:
I’m going to describe how we publish a blog post. Turn it into a numbered checklist with one action per step. Mark any step where something can go wrong, and add a short “if this happens” note.
Raw notes in, clean checklist out. Then you correct it, because you know which step it got wrong.
Create a handover file
If you’re passing a site to someone else, ask AI to turn your notes into a handover document: where the domain is registered, where the site is hosted, who has access, what’s scheduled. Documentation for websites: the handover file covers what belongs in it, and training clients to update their own site is the human side.
Write instructions for non-technical people
Rewrite these steps for someone who has never logged in to WordPress. Use short sentences. Don’t use jargon. Add a sentence after each step saying what they should see on the screen.
This works well because AI is good at changing the reading level without changing the facts. Just check that the screens it describes match what the person will really see.
Record, transcribe, tidy
If you’d rather talk than type, record yourself doing the task and have the recording transcribed, then ask the AI to turn it into steps. See AI for subtitles and transcripts for how.
What can go wrong
- Plausible but wrong. AI writes with equal confidence whether it’s right or not. The more it has to guess, the more it makes up. Always test the steps by following them.
- Documentation that describes what the code should do. If you paste a spec and the code differs, the AI may describe the spec. Check which one you gave it.
- Private data in prompts. Don’t paste passwords, API keys, customer data or anything you wouldn’t send to a stranger. Remove them first. See giving AI tools access to files and apps safely.
- Docs that go stale. An outdated document is worse than none, because people trust it. Put the date at the top and update it when things change.
- Nobody reads it. Keep documents short and stored where people actually look.
A simple routine
- Finish a piece of work.
- Ask AI for a draft explanation or checklist of what you just did.
- Correct it and add the “why”.
- Save it next to the thing it describes (in the project folder, or in the shared drive).
- Date it.
Ten minutes after finishing a task is the cheapest time to document it. You still remember everything, and the AI can do the typing.
A quick checklist
- Did I test the steps by following them?
- Have I added the reasons, not just the actions?
- Is any private information left in the text?
- Is it short enough that someone will read it?
- Is there a date on it?
Key takeaways
- Let AI draft the what; you supply the why.
- Ask it to flag gaps rather than guess.
- Test every set of instructions by following them.
- Keep documents short, dated and close to the work.
Related reading
- Using two AI tools together
- AI and APIs: connecting tools without being a developer
- Custom GPTs explained: what you can build without code
What’s the one process in your work that only exists in your head right now?