If there’s one thing Python developers collectively agree on, besides PEP 8 and the fact that “import this” is a fun Easter egg nobody uses, it’s this: writing documentation is that one task we all procrastinate harder than cleaning the lint filter in a shared apartment dryer. We all want clean, readable docstrings and user guides. We also want to keep shipping features, fixing bugs, and pretending that “I’ll document it later” is a real plan.
Spoiler: it never is.
But we’re in a pretty interesting era now. Large language models—ChatGPT included—aren’t just toys for generating fantasy world lore or “explain quantum physics like I’m five.” They’ve quietly become extremely competent at turning your messy Python source tree into documentation that won’t embarrass you in front of other developers. And if you know how to use the tool properly, you can basically treat ChatGPT like your personal documentation intern who works instantly, doesn’t get tired, and most importantly, doesn’t argue about tabs vs spaces.
This blog is essentially a walkthrough of how you, as a Python developer who already has opinions about static type checking and how modulo should behave, can use ChatGPT to document your codebases in a way that feels natural, consistent, and maintainable. And instead of giving you generic “ChatGPT is cool” marketing talk, we’ll get hands-on with techniques, prompts, and workflows that work in real Python projects—everything from single-file scripts to multi-module packages.
No copying from other articles. No “five reasons why AI will revolutionize documentation.” Just practical, technical, developer-to-developer talk.
Table of Contents
Why We Even Bother With Documentation
We both know documentation isn’t optional—not if you want future-you or future-coworker-you to survive. But the painful truth is that writing docs demands two mindsets at once: the engineer who built the system and the user who didn’t. That’s exactly the split-brain experience that makes documentation mentally taxing.
And here’s where ChatGPT helps. It’s not magical, it’s not replacing technical writers, and it’s certainly not reading your mind. But it is very good at acting as the “fresh eyes” that your own brain simply can’t provide after staring at the same module for six months.
Think of ChatGPT less like an auto-doc generator and more like a thought partner. Give it your function, class, module, or even an entire repo, and it will tell you: “Hey, this thing actually does X, Y, and Z… do you want me to phrase that in a clear way?” That alone is weirdly helpful when your codebase has grown tentacles.
Walking ChatGPT Through Your Python Code
The most common use case is feeding ChatGPT chunks of code and asking it to help you produce docstrings. And no, docstrings aren’t just fancy comments—they’re how you communicate API behavior, assumptions, invariants, tricky edge cases, and what happens if someone passes a None where they shouldn’t.
When using ChatGPT, the key is not dumping your entire project and praying for a perfect response. It’s guiding the model with the right kind of context and intention.
Picture this: you have a Python function like this messy thing:
def normalize_vector(vec):
s = sum(v*v for v in vec) ** 0.5
return [v/s for v in vec]You know what it does. I know what it does. But imagine being a new developer in the repo and finding this buried deep in utils.py. You’d probably mutter something like “cool, another unnamed math helper doing something suspiciously important.”
If you paste this function into ChatGPT and say ‘document this,’ it will generate a docstring. But the real effectiveness comes from specifying how you want it documented. For example, you can literally instruct:
“Generate a docstring in NumPy style, targeted at developers who understand linear algebra. Include computational caveats, like division by zero, and assumptions about the shape of vec. Avoid explaining basic Python concepts.”
ChatGPT then switches mental gears. It stops explaining what a list is and starts thinking like a developer writing API docs for other developers. The resulting docstring reads like something you’d find in a real scientific computing library. And yes, you could write that docstring yourself but if it’s 3 AM and documentation is the last thing between you and sleep, delegation feels pretty good.
Treat ChatGPT As a Junior Python Developer
The best mental model for using ChatGPT in documentation is this: imagine you have a junior dev sitting next to you. They’re smart but new to the project. They read your function, and they explain to you what they think it does.
Sometimes they get details slightly wrong. Sometimes they over-explain. Sometimes they nail it. Your job is to correct and guide, not blindly accept or dismiss.
ChatGPT is not a magical documentation oracle. But it’s very good at:
– Turning messy mental models into structured explanations
– Rewriting docs to match a consistent style
– Expanding short explanations into full ones
– Shrinking overly verbose ones
– Making implicit behavior explicit
– Translating internal logic into developer-friendly English
Language models like ChatGPT do not replace your judgment, but they remove the friction of starting from a blank document.
Asking ChatGPT to Generate High-Level Documentation for Python Code
One of the most underrated uses of ChatGPT is producing documentation above the code level: module overviews, package introductions, README files, architecture overviews, diagrams, even internal documentation for new developers joining the project. If you tell ChatGPT:
“Summarize the architecture of this module. Explain what interacts with what, and why. Assume the reader already knows Python but not this codebase.”
You suddenly get a bird’s-eye view of your own system.
Why is that useful? Because developers often build things incrementally, function by function, feature by feature. We rarely stop to describe the whole organism. ChatGPT helps you capture that bigger picture. And it’s shockingly accurate at reconstructing data flows and relationships from code you paste into it. Is it perfect? No. But it’s a hell of a good starting point.
Avoiding ChatGPT Pitfalls When Documenting Python Code
This is the part most articles gloss over.
ChatGPT is not infallible. It can misunderstand your intentions, hallucinate nonexistent behavior, or “fill in the blanks” too aggressively. If you feed it a function with side effects, it might not detect them. If your function has tricky asynchronous behavior or edge cases involving sockets, threading, or complex generators, you should always verify the AI-generated docstring.
The key is to treat ChatGPT’s documentation as a first draft—an assistant-generated brain dump. You review it like a PR in your own repo. You make sure it aligns with how the code actually behaves.
Think of ChatGPT as the world’s fastest junior developer: amazingly helpful, sometimes wrong, never malicious, and great at producing drafts you can refine.
Can ChatGPT Replace Human Documentation?
No. And it shouldn’t. Human-written documentation has nuance and intent and domain knowledge that an LLM can’t fabricate. But ChatGPT amplifies your ability to write documentation. It saves time, reduces friction, and helps you maintain high-quality documentation across an entire project.
Documenting software shouldn’t feel like dental work. ChatGPT makes it feel more like pair programming with someone who genuinely enjoys writing.
Final Thoughts
ChatGPT won’t make you a magically better developer. It won’t write your architecture. It won’t save a fundamentally broken design. But it will take the most annoying part of your workflow — documenting things — and make it dramatically easier, faster, and more pleasant. And the more you use it, the more you’ll start seeing documentation as part of writing software instead of a separate punishment.
You still own the final output. But ChatGPT gives you all the scaffolding, structure, and clarity you need to document Python code without burning half your weekend.
If you’re not already using it this way, start with one small file. One script. One module. Let ChatGPT draft the docs. You refine them. You’ll never go back. Looking for a small yet interesting project to start with? Boy do I have suggestions for you:
- OpenCV is always fun. Get started with this image processing exercise using OpenCV in Python. Try documenting the project.
- Looking for a little more challenging project? Why not imagine yourself to be a software company releasing this OpenCV app and you are looking to document it?
- Or maybe you don’t want image processing at all! You just want a simple Python program and want to have a little fun. Check out this quiz generated in Python to check if you are a real programmer from the Pathetic Programming series where you develop silly Python code, just to get fun out of it.
Whichever project you choose, feel free to share your results with me on Instagram or simply drop a “Hey, what’s up?”: @machinelearningsite. Have fun coding and documenting. Peace!