AI and documentation: a practical workflow that actually works

Documentation is like the dentist — everyone knows they should, nobody wants to. AI changes this. Not by writing perfect docs for you, but by turning a half-day task into a half-hour one. And the result is often better, because AI doesn't skip 'obvious' details that you take for granted.

What AI can do in documentation

AI excels at generating the first draft — and the draft is 80% of the work. Here's what you can delegate with high output quality:

• JSDoc/docstrings from code — AI reads the function and writes description, parameters, return values
• README for a module based on its API and structure
• Changelog from git history — AI reads commits and generates a readable changelog
• Architecture documentation from existing code — data flow, dependencies, modules
• Translation of internal docs to another language
• API documentation from endpoints — request/response formats, examples

# Prompt for module documentation:

Read all files in src/services/payment/
and write documentation:

1. Overview — what the module does, one paragraph
2. Architecture — how files relate to each other
3. API — public functions with params and examples
4. Dependencies — what the module needs
5. Known limitations and tech debt

Format: Markdown, concise, no marketing.

What AI cannot do in documentation

Explain WHY. Documentation that says 'this function does X' is useless — I can see that in the code. Documentation that says 'we created this function because the previous approach Y had problem Z, and we chose this solution because...' — AI doesn't know that.

AI also can't reliably document implicit team knowledge: 'Never migrate this table on Friday.' 'This endpoint uses a different auth flow than all others.' 'This variable is badly named, but renaming it would break 15 external integrations.' This has to come from a human.

Practical workflow in three steps

Step 1: AI generates the base from code

Give AI access to the codebase (Claude Code, Cursor) and tell it: 'Write documentation for [module/function/API]. Include overview, API description, usage examples, and known limitations.' AI reads the code and generates the first draft.

Step 2: You add context, reasons, and nuances

Review the draft and add: why we did it this way, what alternatives we considered, what gotchas aren't visible from the code. This is the part only you can do — and thanks to AI, you can focus exclusively on it.

Step 3: AI formats and refines

After your edits, let AI finalize: 'Format this document consistently. Add missing examples. Check that all API descriptions match the actual code.' AI polishes the structure and catches inconsistencies.

Concrete use cases that work

CLAUDE.md as living documentation

CLAUDE.md at the project root serves as a document for AI agents — but also as excellent documentation for new team members. It contains stack, build commands, conventions, important decisions. And because AI actively uses it, it stays current — unlike a wiki that everyone ignores.

# CLAUDE.md — living documentation example

## Stack
Next.js 16, TypeScript, Tailwind, Prisma

## Conventions
- Functions: camelCase, components: PascalCase
- Tests: vitest, files: *.test.ts
- Commit messages: conventional commits

## Key decisions
- Auth: JWT + httpOnly cookies (not sessions)
  Reason: microservices need stateless auth
- DB: Postgres + Prisma (not TypeORM)
  Reason: better type safety, simpler migrations

Automatic changelog from git history

Instead of writing changelogs manually: 'Read the git log for the last 2 weeks and generate a changelog. Group changes by: features, fixes, refactoring. Describe changes from the user's perspective, not the developer's.'

Onboarding guide from existing code

'Write an onboarding guide for a new developer on this project. Include: how to start locally, key files and modules, architecture overview, where to look first.' AI reads the entire project and creates a guide that would take you half a day to write manually.

Result: documentation that exists

Existing documentation is infinitely better than perfect documentation that doesn't exist.

AI won't lower the barrier to zero — you still need to add context and verify accuracy. But it lowers the barrier enough that documentation stops being a task you postpone 'until next time.' And that changes everything.