AI Documentation: Generated Docs That Stay Current
AI-assisted documentation: using AI tools to generate and maintain documentation — READMEs, API references, JSDoc/TSDoc comments, architecture overviews, and onboarding guides. The developer: describes what needs to be documented or prompts the AI with existing code. The AI: generates documentation in the appropriate format, following the project's documentation conventions (if specified in the rules). The output: documentation that would take a developer 30-60 minutes to write, generated in 1-2 minutes.
The documentation problem AI solves: developers write code but not documentation. The code: maintained and updated regularly. The documentation: written once and never updated. After 6 months: the README describes the setup process from 6 months ago (which has changed), the API docs reference endpoints that were renamed, and the architecture overview describes a monolith that was split into services. AI documentation: generated from the current code, so it reflects the current state. Regenerate after changes: the docs stay current.
Types of AI-generated documentation: code comments (JSDoc/TSDoc for functions — parameter descriptions, return types, usage examples), READMEs (project overview, setup instructions, development commands), API documentation (endpoint descriptions, request/response schemas, error codes), architecture docs (module relationships, data flow, deployment topology), and changelog entries (summarizing what changed in a commit or PR). Each type: well-suited for AI generation because the source information exists in the code.
What AI Documentation Does Well (and Does Not)
AI documentation strengths: describing what code does (the AI reads the function and explains its behavior accurately), generating consistent format (every JSDoc comment follows the same structure), covering every function (the AI does not get bored or skip functions — it documents everything asked), and maintaining freshness (regenerate from current code = current documentation). These strengths: make AI ideal for mechanical documentation tasks where comprehensiveness and consistency matter.
AI documentation limitations: explaining why code exists (the AI does not know the business rationale — why this feature was built, why this approach was chosen over alternatives), providing context beyond the code (the AI cannot document the meeting where the architecture was decided), writing tutorials from the user's perspective (the AI knows how the code works but not how a user experiences the feature), and maintaining a narrative voice (AI-generated docs can feel mechanical — technically correct but lacking the human touch that makes documentation engaging).
The partnership: AI generates the what (function descriptions, parameter lists, return types, error codes). The developer adds the why (business context, design decisions, trade-offs, and the human narrative). The combination: comprehensive documentation that is both technically complete (AI) and contextually meaningful (human). Neither alone: is sufficient. Together: documentation that developers actually read and trust. AI rule: 'AI writes the what. The developer adds the why. The AI handles: structure, format, and technical accuracy. The developer handles: context, rationale, and narrative.'
The function was refactored: new parameters, new return type, new error handling. The JSDoc: still describes the old version. Without regeneration: the documentation is wrong. With AI regeneration: 'Update the JSDoc for createUser to match the current implementation.' The AI: reads the current function and generates accurate JSDoc. 30 seconds. The documentation: current. The alternative (manually updating JSDoc after every refactoring): rarely happens. AI regeneration: makes freshness effortless.
How Rules Improve AI-Generated Documentation
Documentation rules: CLAUDE.md can include rules for documentation style. 'JSDoc: every exported function has JSDoc with @param, @returns, and a one-line description. No JSDoc for internal functions.' 'README: includes Purpose, Setup, Development, Testing, and Deployment sections.' 'API docs: OpenAPI/Swagger format. Every endpoint: description, request schema, response schema, error codes.' These rules: ensure AI-generated documentation matches the project's documentation standards.
Without documentation rules: the AI generates JSDoc in one format for file A and a different format for file B (no consistency). With documentation rules: every JSDoc follows the same format across the entire codebase. The consistency: makes the documentation more professional and easier to read. The rules: save time on documentation review (no comments about formatting — the AI already formatted correctly).
When to document in rules vs when to let AI decide: document in rules: the documentation format (JSDoc structure, README sections, API doc format), which elements need documentation (exported functions: yes, internal helpers: no), and the documentation voice (technical reference style, tutorial style, or enterprise style). Let the AI decide: the specific wording of descriptions (the AI reads the code and describes it), the parameter descriptions (the AI infers from the type and usage), and the examples (the AI generates realistic examples from the function signature). AI rule: 'Rules: define the format and scope. The AI: fills in the content. The developer: adds context and reviews accuracy.'
AI-generated JSDoc: '@param id - The user ID to look up. @returns The user object or null if not found.' Technically correct. But missing: why this function exists (it is the primary user lookup used by the authentication flow), what happens in practice (returns null for deactivated users, not just non-existent ones), and the historical context (originally returned an error for deactivated users, changed to null in Q2 after product team feedback). The developer: adds 2 sentences of context. The documentation: transforms from technical description to useful knowledge.
Using AI Documentation Effectively
Generating documentation for existing code: 'Add JSDoc comments to all exported functions in src/services/user-service.ts. Follow our documentation conventions.' The AI: reads each function, generates JSDoc with @param, @returns, and a description. The developer: reviews for accuracy (does the description match the actual behavior?) and adds context (why does this function exist? What business requirement does it serve?).
Maintaining documentation freshness: after a significant code change: regenerate the affected documentation. 'Update the JSDoc for the refactored createUser function to reflect the new Result pattern return type.' The AI: updates the documentation to match the new code. The documentation: stays current with the code. The alternative (manually updating documentation after every code change): rarely happens. AI regeneration: makes documentation maintenance effortless.
README generation: 'Generate a README for this project with: Purpose (what the project does), Setup (how to install and configure), Development (how to run locally), Testing (how to run tests), and Deployment (how to deploy).' The AI: reads the project files (package.json, configuration files, CI workflow) and generates accurate setup instructions. The developer: reviews for accuracy and adds context (why the project exists, who it serves, and any important caveats). AI rule: 'AI-generated READMEs: accurate for technical content (commands, configuration). Less accurate for context (purpose, audience, history). Review technical accuracy. Add context manually.'
The AI reads package.json and generates: 'Setup: pnpm install. Dev: pnpm dev. Test: pnpm test. Build: pnpm build.' Accurate: these commands work. But: the AI also generates 'Purpose: A Next.js application for managing user data.' Partially accurate: it is a Next.js app, but its purpose is more specific (it is a patient portal for healthcare providers, not a generic user data app). Review: the AI's technical content (commands, configuration) is usually accurate. The AI's contextual content (purpose, audience): needs human review and refinement.
AI Documentation Quick Reference
Quick reference for AI-assisted documentation.
- What: AI generates READMEs, API docs, JSDoc, architecture overviews, and changelogs from code
- Strengths: describes what code does, consistent format, comprehensive coverage, freshness from regeneration
- Limits: cannot explain why (business context), write user tutorials, or provide engaging narrative
- Partnership: AI writes the what (technical descriptions). Developer adds the why (context and rationale)
- Rules: define format (JSDoc structure, README sections, API doc format). AI fills in content
- Freshness: regenerate after code changes. AI reads current code = current documentation
- README: AI reads project files and generates accurate setup. Developer adds purpose and context
- Review: check technical accuracy (does the description match the code?). Add business context