AI for documentation

Documentation is time-consuming and AI can draft it quickly. The catch is that AI can invent details or drift from the actual API. Use AI for a first draft, then verify every claim against the code and runtime behavior.

Why AI is good for documentation

Documentation has predictable structure:

• README: purpose, setup, usage, configuration
• JSDoc: parameters, returns, examples
• API docs: endpoints, request/response, status codes

AI can generate these structures quickly. The challenge is accuracy. AI describes what it thinks the code does, which may differ from reality.

What AI documentation gets wrong

Always verify before publishing.

Draft READMEs and overviews

Ask for a README that covers purpose, setup, and basic usage. Give context so the draft matches your project:

Good prompt:

Write a README for this project.

package.json: [paste]
Main entry point: src/index.ts
Tech stack: Next.js 14, TypeScript, Tailwind CSS

Include:
- Project description
- Getting started (prerequisites, installation, dev server)
- Available scripts
- Folder structure overview

Then verify:

• Prerequisites are correct (Node version, package manager)
• Installation commands work
• Dev server command works
• Folder structure matches reality
• No invented features or dependencies

Generate JSDoc or TSDoc from code

For functions and types, ask the AI to write documentation from the signature:

Good prompt:

Write JSDoc for this function. Include:
- Description of what it does
- @param descriptions with types
- @returns description
- @throws if it can throw
- @example with working code

function parseUserInput(input: string, options?: ParseOptions): ParseResult {
  // [implementation]
}

Then verify:

• Parameter descriptions are accurate
• Return type description matches actual behavior
• Any @throws are real exceptions this function can raise
• Example code runs correctly

When to skip JSDoc

Not every function needs documentation:

API docs need a reality check

API documentation is high-stakes. Wrong docs confuse users and erode trust.

For each endpoint, verify:

• URL path is correct
• HTTP method is correct
• Request body schema matches real implementation
• Response schema matches real implementation
• Status codes are accurate
• Example requests work when executed
• Example responses are real, not invented

Testing API documentation

Do not just read the docs. Test them:

# For each example request in your docs
curl -X POST https://api.example.com/endpoint \
  -H "Content-Type: application/json" \
  -d '{"example": "data"}'

# Verify the response matches the documented response

If the example does not work, fix the docs before publishing.

Keep examples runnable

Code samples in documentation must run. Non-working examples frustrate users.

Verification checklist:

• Paste example into a file in your project
• Run it
• Verify output matches what docs say
• Update paths, imports, and sample data if needed

Common issues in AI examples:

• Wrong import paths
• Missing dependencies
• Outdated API calls
• Hardcoded values that do not exist
• Missing error handling

Fix all of these before publishing.

Own the final wording

AI drafts may not match your project's voice:

Adjust the draft so it matches your project's voice and is accurate. Documentation is part of your product.

Documentation workflow with AI

1. Draft with AI: Ask for README, JSDoc, or API docs with relevant context
2. Verify accuracy: Check every claim against real code and behavior
3. Run examples: Execute all code samples
4. Adjust tone: Match your project's voice
5. Update imports/paths: Ensure they match your project
6. Review with fresh eyes: Read as if you are a new user
7. Publish: Only after full verification

Types of documentation and AI effectiveness

When to rewrite instead of edit

Sometimes AI drafts are too far off:

Rewrite from scratch if:

• More than half the claims are wrong
• The structure does not fit your documentation style
• Examples are fundamentally broken
• The tone is completely wrong

Edit the AI draft if:

• Structure is good, details need correction
• Most information is accurate
• Examples need minor fixes
• Tone needs slight adjustment

Summary

AI speeds up documentation by generating first drafts quickly. Your job is verification:

1. Draft with AI: Provide context for accurate results
2. Verify everything: Check every claim against real code
3. Run all examples: Broken examples are worse than no examples
4. Match your voice: Adjust tone and style
5. Never publish unverified drafts: AI invents details that look plausible

For more on using AI without losing control, see AI-assisted coding: practical tips and Reviewing AI-generated code.