This is Part 6 of “The Centaur’s Toolkit” series, where we explore practical strategies for human-AI collaboration in technical work.
Nobody likes writing documentation. I’ve never met a developer who wakes up excited to document their code. We know it’s important. We know future-us will be grateful. We still procrastinate until the last possible moment, then write the bare minimum.
This isn’t a character flaw. It’s a rational response to incentives. Documentation takes time, provides no immediate feedback, and often becomes outdated before anyone reads it. The effort-to-reward ratio feels terrible.
AI changes this equation. Dramatically.
But not in the way you might think. The solution isn’t “let AI write all your documentation.” That path leads to verbose, generic docs that nobody trusts. The solution is understanding what AI does well, what humans must still own, and how to combine them effectively.
Why Documentation Fails
Before we talk about AI, let’s be honest about why documentation fails in the first place.
It’s written once and never updated. Code changes. Documentation doesn’t. Within months, docs describe a system that no longer exists.
It’s written by the wrong people at the wrong time. The person who understands the code best is deep in implementation mode. They write docs when they’re exhausted from building, not when they’re fresh and able to explain clearly.
It optimizes for completeness over usefulness. We document everything because we’re not sure what matters. The result is a wall of text where the critical information is buried in the middle of page 47.
It assumes too much or too little. Docs written by experts skip “obvious” concepts that beginners need. Docs written for beginners bore experts who just want the API reference.
Nobody owns it. Documentation is everyone’s responsibility, which means it’s nobody’s responsibility. It rots in a wiki somewhere, unloved and unmaintained.
AI can address some of these problems. Others it makes worse if you’re not careful.
What AI Does Well in Documentation
Let me be specific about where AI genuinely helps.
First Drafts from Code
AI is excellent at generating initial documentation from code. Give it a function, and it will produce a docstring. Give it a module, and it will produce an overview. Give it an API, and it will produce endpoint descriptions.
You: Document this function with a clear description,
parameter explanations, return value, and example usage.
def calculate_retry_delay(attempt: int, base_delay: float = 1.0) -> float:
return min(base_delay * (2 ** attempt), 30.0)
AI: """Calculate exponential backoff delay for retry attempts.
Args:
attempt: The current retry attempt number (0-indexed)
base_delay: Initial delay in seconds (default: 1.0)
Returns:
Delay in seconds, capped at 30 seconds maximum
Example:
>>> calculate_retry_delay(0) # First retry
1.0
>>> calculate_retry_delay(3) # Fourth retry
8.0
"""
This isn’t magic. The AI is pattern-matching against millions of documented functions it’s seen. But that pattern-matching is useful. The first draft captures the obvious stuff, the structure, the parameter names and types. It gives you something to edit rather than a blank page.
The key insight: AI drafts are starting points, not finished products. You still need to add the “why,” the edge cases, the context that the code alone doesn’t reveal.
Explaining Code to Different Audiences
AI can translate between expertise levels. Take technical documentation and ask for a beginner-friendly version. Take a simple explanation and ask for the technical details an expert would want.
You: Here's our authentication flow documentation.
Rewrite it for a developer who's never worked
with OAuth before. Explain concepts they might
not know.
AI: ## Authentication Overview
Before your app can access user data, it needs permission.
OAuth is the industry-standard way to get that permission
without users sharing their passwords with you.
Here's how the flow works:
1. Your app redirects users to our login page
2. Users approve access (they see exactly what you're requesting)
3. We redirect back to your app with a temporary code
4. Your server exchanges that code for an access token
...
This is genuinely useful. A single source document can generate multiple versions for different audiences. The expert docs stay precise. The beginner docs stay accessible. Both come from the same underlying truth.
Filling in Obvious Gaps
AI is good at noticing what’s missing. Ask it to review documentation and identify gaps, and it will often catch things you’ve overlooked.
You: Review this API documentation. What information
is missing that a developer would need to actually
use this endpoint?
AI: The documentation doesn't mention:
- Rate limiting policies
- Authentication requirements
- Error response formats
- Pagination for list endpoints
...
This works because AI has seen thousands of API docs. It knows the standard sections. It notices when yours is missing something typical.
Converting Formats
Need to turn a README into a wiki page? Convert inline comments to a separate docs file? Transform a spec document into user-facing help text?
AI handles format conversions well. The information stays the same; the presentation changes. This is mechanical work that AI does faster and more consistently than humans.
What AI Does Poorly
Now the harder truth. AI documentation has real limitations that you need to understand.
The “Why” Behind Decisions
Documentation’s most valuable content explains why things are the way they are. Why did we choose this architecture? Why is this parameter required? Why does this edge case exist?
AI can’t answer these questions. It wasn’t in the room when decisions were made. It doesn’t know about the performance issue that drove the caching strategy, or the compliance requirement that necessitated the audit logging.
AI-generated docs are often technically accurate but contextually empty. They describe what the code does without explaining why it matters.
Accuracy on Specifics
AI hallucinates. In documentation, this means invented parameters, incorrect default values, and plausible-sounding but wrong explanations. The problem is worse for newer or less common libraries where training data is sparse.
I’ve seen AI-generated docs that were 90% accurate and 10% dangerously wrong. The 10% was presented with the same confidence as the 90%, making it hard to spot without careful verification.
Maintaining Consistency
AI doesn’t remember your previous documentation decisions. Each generation is independent. Ask it to document ten endpoints, and you’ll get ten slightly different styles, terminology choices, and structural approaches.
This inconsistency compounds over time. Your docs become a patchwork of AI generations rather than a coherent whole.
Understanding Your Users
Good documentation anticipates what users will struggle with. It emphasizes the tricky parts and glosses over the obvious ones. This requires understanding your actual users, their backgrounds, and their common mistakes.
AI knows generic users. It doesn’t know your specific users. It will emphasize things that are obvious to your audience and skip things they actually need.
The Centaur Approach to Documentation
Here’s how I actually use AI for documentation, combining its strengths with human judgment.
The Three-Layer System
I think of documentation as three layers, each with different AI involvement.
Layer 1: Reference Documentation
This is the factual stuff. API endpoints, function signatures, configuration options. It answers “what does this do?” without much context.
AI involvement: High. AI generates first drafts from code. Humans verify accuracy and add edge cases.
Layer 2: Conceptual Documentation
This explains how things work together. Architecture overviews, data flow diagrams, getting started guides. It answers “how does this fit together?”
AI involvement: Medium. AI helps with structure and format. Humans provide the actual concepts and connections.
Layer 3: Decision Documentation
This explains why. Architecture decision records, design rationales, historical context. It answers “why is it this way?”
AI involvement: Low. Humans write these. AI might help with formatting or completeness checks, but the content must come from people who were there.
The Documentation Workflow
For any significant documentation task, I follow this process.
Step 1: Human outlines the structure.
Before touching AI, I decide what sections exist, what questions each section answers, and what expertise level we’re targeting. This is strategic work that requires understanding the audience.
Step 2: AI generates first drafts.
For each section, I give AI the relevant code or context and ask for a draft. I’m specific about format, length, and audience.
You: Write the "Authentication" section of our API docs.
Target audience: developers familiar with REST APIs
but new to our system. Include: overview, required
headers, token format, refresh flow, common errors.
Keep it under 500 words.
Step 3: Human reviews and revises.
This is where the real work happens. I verify accuracy against actual code. I add the “why” that AI missed. I catch hallucinations. I ensure consistency with existing docs.
This step often takes longer than writing from scratch would have. But it’s a different kind of work. Editing is easier than creating. I’m improving rather than generating.
Step 4: Human adds context and connections.
After the draft is solid, I add the parts AI can’t know. Links to related docs. Warnings about common pitfalls. References to design decisions. The institutional knowledge that makes docs actually useful.
Step 5: AI reviews for gaps.
Finally, I ask AI to review the finished documentation for missing information or unclear explanations. Fresh eyes, even artificial ones, catch things I’ve become blind to.
Dealing with Hallucinations
AI documentation hallucinations are insidious because they look right. A fake method name looks like a real method name. An incorrect default value looks like a correct one.
My verification protocol:
Always test code examples. If the docs include code, run it. AI-generated examples often have subtle bugs or use deprecated patterns.
Verify against source. For any specific claim (this parameter defaults to X, this method returns Y), check the actual code. Don’t trust AI memory of code it read moments ago.
Flag uncertainty. When I’m not sure about something AI generated, I flag it with a comment for later verification rather than assuming it’s correct.
Separate fact from interpretation. AI statements of fact (“this function returns a string”) can be verified. AI interpretations (“this approach is more efficient”) need human judgment.
The Maintenance Problem
Here’s where AI documentation gets tricky: maintenance.
Code changes constantly. Documentation needs to change with it. AI can help regenerate docs when code changes, but this creates new problems.
Regeneration loses human additions. You spent time adding context, warnings, and explanations. If AI regenerates the doc from updated code, all that work disappears.
Drift detection is hard. How do you know when documentation has become stale? AI can compare docs to code, but it might flag stylistic differences as errors or miss semantic changes.
Version control becomes complex. Which documentation corresponds to which code version? AI-generated docs from yesterday’s code might be wrong for today’s code.
I haven’t solved this problem cleanly. My current approach:
Separate generated and authored content. Reference docs that AI generates live in one place. Human-authored context lives in another. When code changes, regenerate the reference docs; the context stays stable.
Document the generation process. For any AI-generated doc, I note what prompt produced it and what version of the code it reflects. This makes regeneration reproducible.
Regular human review cycles. Quarterly, I review all documentation for staleness. This is manual and tedious, but necessary. AI can help identify candidates for review; humans must actually review.
When to Skip AI Entirely
Some documentation shouldn’t involve AI at all.
Architecture Decision Records (ADRs). These capture why decisions were made. Only humans who made the decisions can write them. AI has no relevant input.
Incident postmortems. These require honesty about what went wrong. AI might soften language or miss the human factors that actually matter.
Sensitive or regulated content. Anything with compliance implications needs human review anyway. Adding an AI step just adds risk without meaningful benefit.
Documentation for AI systems themselves. Ironic but true. Documenting how your AI integration works shouldn’t rely on AI that might misunderstand its own context.
The Real Productivity Gain
Let me be honest about what AI actually provides for documentation: it lowers the activation energy.
The hardest part of documentation isn’t writing. It’s starting. The blank page is intimidating. The task feels overwhelming. So we procrastinate.
AI eliminates the blank page. Even a mediocre first draft is easier to improve than nothing. Even a flawed structure is easier to fix than no structure.
This psychological benefit might be AI’s biggest contribution to documentation. Not the quality of what it writes, but the fact that it writes anything at all. It gets you past the starting friction.
Once you’re editing rather than creating, momentum takes over. The documentation gets done. Maybe it takes the same total time, maybe even longer. But it happens, instead of being perpetually deferred.
The Trust Question
Can you trust AI-generated documentation? Users will ask this, explicitly or implicitly.
My answer: trust it exactly as much as you’d trust any documentation, which is to say, verify anything critical.
AI-generated docs aren’t inherently less trustworthy than human-generated docs. Both can be wrong. Both can be outdated. Both can be incomplete. The failure modes are just different.
Human docs fail through neglect, expertise assumptions, and inconsistent updates. AI docs fail through hallucination, missing context, and generic advice. This connects to the broader challenge of calibrating trust in AI output; documentation is just another domain where verification matters.
Good documentation practices apply regardless of origin: version control, regular review, user feedback loops, testing of examples. These practices catch errors whether humans or AI made them.
The Centaur approach treats AI as a collaborator who’s good at some things and bad at others. Not a replacement for human judgment, but an amplifier of human productivity.
How do you handle documentation? Are you using AI to draft docs, or do you find the verification overhead makes it not worth it? I’d like to hear what’s working in your workflow. Find me on X or LinkedIn.
What’s Next
We’ve covered the major applications of AI collaboration: pair programming, security tooling, trust calibration, code review, tool selection, and now documentation. But we haven’t addressed the question many people are actually asking: what happens to my job?
AI is changing what technical work looks like. Some tasks are being automated. Some are being transformed. What skills matter going forward? How do you position yourself for the AI-augmented future?
Next in the series: The Evolving Role of the Technical Professional in an AI World
Documentation is one area where human-AI collaboration shows clear benefits alongside real pitfalls. For the complete framework on building effective AI partnerships across all aspects of technical work, check out The Centaur’s Edge: A Practical Guide to Thriving in the Age of AI.