How to use Claude for documentation generation

Claude documentation generation works best when you point the model at real artifacts (route handlers, OpenAPI specs, merged PRs, Slack incident threads) and ask for one specific output shape. Claude wins on consistency and completeness across hundreds of endpoints. It loses on intent, novel architecture, and team voice. Use it for the boilerplate 80%, edit the rest by hand.

That answer is short for a reason. The teams with current docs in 2026 are not debating whether to use AI for docs. They are running Claude Code against their main branch, opening doc PRs on Mondays, and editing the 20% the model gets wrong. This post walks through the eight surfaces Claude handles well, the prompt patterns that work, and where humans still beat the model.

What Claude is actually good at for docs

Claude is good at structured-input, structured-output translation. Give it a route file plus a TypeScript interface, get an OpenAPI block back. Give it a PR diff plus the previous changelog, get the next changelog entry. The model is bad at inventing intent that is not in the input.

When developers say "Claude wrote our docs," they mean one of three modes:

• Claude Code in the terminal, file-aware, can read the tree and write to disk.
• Claude.ai in the browser, paste-and-respond. Good for one-off drafts.
• Claude API in a CI pipeline. What Mintlify, Fern, and Scalar use under the hood for "open a doc PR when code changes."

Same model in each. The difference is context volume and automation. Anthropic publishes its own skills repo with reusable Claude skill definitions including documentation skills, a useful starting point for copying a working pattern instead of inventing one.

The 8 documentation surfaces Claude handles well

Each of these is a different input shape and a different output target. Treat them as separate pipelines.

1. Generating CLAUDE.md from an existing codebase

CLAUDE.md is the file Claude Code reads at the start of every session. It tells the model your build commands, coding standards, and architecture conventions. The fastest way to bootstrap one is to ask Claude Code itself.

Prompt template:

Read the package.json, the top-level README, and the src tree. Generate a CLAUDE.md with these sections: Terminal commands, Workflows, Coding standards, Domain terminology, Architecture and structure. Keep it under 300 lines. Use bullet lists, not prose.

This gets you 80% of the file in five minutes. You add the domain terminology section by hand because the model cannot infer that "Wraps" means video summaries from your code.

2. README from the codebase

A good README has six sections: what this is, who it is for, install, quickstart, configuration, and where to find more. Claude can produce all six if you point it at the package manifest, the entry point, and any existing docs folder.

Prompt template:

Generate a README.md for this project. Read package.json, src/index.ts, and the existing docs folder. Sections: Overview, Install, Quickstart, Configuration, Deployment, Where to find more. Show install with the actual package manager (pnpm). Show quickstart with a runnable code block.

Claude beats humans on completeness. It catches the install step you forgot to document because new hires stub their toes on it.

3. API reference from OpenAPI specs

This is where Claude saves the most time. If you have an OpenAPI spec, you can pipe it into Mintlify, Fern, or Scalar and get a generated reference site. If you do not have a spec, you can ask Claude to produce one from your route handlers, then pipe the spec.

Prompt template for spec generation:

Read every file in src/routes. For each route, extract: HTTP method, path, request schema (from the type annotation), response schema, error codes, auth scope. Output as OpenAPI 3.1 YAML. Do not invent fields. If a field is unclear, mark it TODO.

Then push the YAML to your docs platform. Mintlify's Workflows agent will monitor changes and open a PR each time the spec moves. Fern generates SDKs from the same spec. Scalar renders a fast, embeddable reference. Pick one and stop hand-writing endpoint pages forever.

4. Code comments and when to skip them

Use Claude for public-API docstrings (JSDoc, Google-style Python, Go doc comments). Skip Claude for inline comments inside function bodies. Inline comments capture the non-obvious "why," and the model cannot read your mind.

A good rule: if a comment answers "what does this code do," Claude can write it. If it answers "why is it written this way," a human writes it.

Prompt template for docstrings only:

For every exported function in this file, add a JSDoc block with a one-line summary, @param entries with types, @returns with type, and @example. Do not touch private functions. Do not add inline comments inside function bodies.

5. Runbooks from code plus Slack history

The killer use case most teams miss. When an incident hits, recovery steps live in three places: the code that broke, the alert config that fired, the Slack thread where engineers debugged. Claude can fuse all three.

Prompt template:

Read the alert config at infra/alerts/checkout.yaml, the handler at src/billing/charge.ts, and the attached Slack thread. Produce a runbook with sections: Symptom, Detection, Diagnosis steps, Mitigation, Root cause history. Link each step to the file or line it touches.

The first runbook is 70% right. Edit once. Future incidents in the same area produce 90%-right drafts because the model picked up your conventions.

6. Changelogs from merged PRs

Every team should have a CHANGELOG.md. Almost none do, because writing it manually is tedious. Claude solves the tedium.

Prompt template:

Read the merged PRs since the last release tag. Group under: Added, Changed, Fixed, Deprecated, Security. Each entry: one user-facing sentence. Skip internal refactors unless they change behavior. Reference the PR number.

Run on release day. Five minutes. The strategic narrative ("this release marks our shift to event-driven architecture") still comes from a human.

7. ADRs (architecture decision records)

ADRs document why you chose option A over option B. Claude can fill in the template: context, options considered, decision, consequences. It cannot invent the dissent that should go in "options considered."

Prompt template:

Using the ADR template at docs/adr/template.md, draft ADR-0042 for the decision in PR #1247. Fill in: Context (from the PR description), Options considered (from the design doc linked in the PR), Decision (the merged approach), Consequences (positive and negative). Mark anything you are unsure about with [REVIEW].

The [REVIEW] markers are the point. They tell the human reviewer where to add tradeoff context that was never written down.

8. Internal wiki updates from code changes

Confluence and Notion pages drift the moment they are written. Claude keeps them in sync if you wire it into CI.

Prompt template:

Read the diff of PR #1832 and the wiki page at the linked URL. If the PR changed behavior the wiki documents, output the updated page. Otherwise output NO_CHANGE.

Pair with a GitHub Action that posts the diff back to Confluence as a draft edit.

Where Claude beats human-written docs

Three places, consistently:

• Consistency. Two hundred endpoint pages, identical shape, every parameter labeled. A human team does this for the first ten and gets bored. Claude does it for the two-hundredth the same way it did the first.
• Completeness. Humans skip the obvious. They forget to document the Authorization header because everyone "knows" it. Claude does not get bored and lists every header.
• Drift fix. The cheapest doc is the one regenerated on every merge. Humans cannot afford to rewrite the API reference each release. Claude can. That changes the economics of doc accuracy.

Teams using Cursor and Claude Code daily ship with docs that match code, because they regenerate constantly. Teams hand-writing docs ship with docs that lag a quarter. The gap compounds. If you want context on where this fits in the broader engineering workflow, our guide to using Claude Code in production walks through the planning loop and CLAUDE.md discipline that make this tractable.

Where humans still win

Four places, also consistently:

• Intent. "Why does this service exist?" is not in the code. It is in a Slack thread from 2024 that nobody saved.
• Novel architecture. When you split a monolith in a non-obvious way, the rationale is the doc. Claude will describe the split. It will not explain the bet.
• Voice. Docs that sound like a person are easier to read. Claude-written prose is fine. It is also forgettable.
• Tradeoff context. "We picked Postgres over Mongo because" needs the dissenting voice. The model writes the consensus. Humans write the disagreement.

The senior engineers we work with at Cadence treat Claude-generated drafts as a 70% starting point. They never ship it raw. They edit for intent and voice, then merge.

The prompt patterns that actually work

Five patterns show up in every working doc-generation prompt:

1. Anchor with real artifacts. Paste the route file. Paste the PR diff. Paste the OpenAPI block. Do not describe what the code does; show it.
2. Specify the output format exactly. "OpenAPI 3.1 YAML." "Markdown with H2 sections in this order." "JSDoc only, no inline comments." Vague format = vague output.
3. Set the audience. "Write for a new hire on day one." "Write for a third-party API consumer who has never seen our product." Same code, different doc.
4. Constrain scope. One file, one endpoint, one decision per call. Long batch prompts produce average outputs. Short scoped prompts produce sharp ones.
5. Ask for the questions Claude cannot answer. End the prompt with: "List anything you are uncertain about with [REVIEW] markers." This converts the model's blind spots into a human checklist.

For doc generation, Sonnet is usually the right tier. Haiku is fine for batch changelog runs. Opus is overkill unless you are generating ADRs that need real reasoning over options. Our breakdown of Claude Opus vs Sonnet vs Haiku covers the cost-quality math, and the comparison across OpenAI, Anthropic, and Google models covers when a different vendor makes sense.

Building it into your team workflow

Stop running Claude doc commands by hand. Wire them into the pipeline.

A working setup looks like this:

• Pre-merge: Claude drafts the changelog entry and proposes a wiki update on PR open. Reviewer accepts or edits inline.
• Post-merge: If the PR description includes a decision: block, Claude generates the ADR draft and opens a follow-up PR.
• Weekly: A scheduled job re-runs README and OpenAPI generation against trunk. If the diff is non-trivial, it opens a doc PR.
• On incident: A /runbook Slack command runs Claude over the alert config plus the current thread, posts a draft runbook back to the channel.

You do not need a vendor for any of this. Claude Code in a GitHub Action, plus a few shell scripts, gets you there. Mintlify, Fern, and Scalar are useful when you want a polished hosted docs site on top.

Doc surface	Input	Where Claude wins	Where humans win
CLAUDE.md	src tree, package.json	Bootstrap in 5 min	Domain terminology, project history
README	src tree, entry points	Install, quickstart, completeness	Why the project exists
API reference	OpenAPI spec or routes	200 endpoints, identical shape	Design rationale, best-practice guides
Code comments	Function bodies	Boilerplate JSDoc, parameter docs	The non-obvious why
Runbook	Code, Slack thread, alerts	Step-by-step recovery	Tribal edge cases
Changelog	Merged PR titles, diffs	User-facing summary, grouping	Strategic narrative
ADR	PR description, diff, chat	Template fill-in, options listed	Real tradeoff analysis, dissent
Internal wiki	PR diff, existing page	Keep page in sync with code	Onboarding stories, escalation maps

If your team does not have someone who already runs this loop, the fastest path is to book an engineer who does. Every engineer on Cadence is AI-native by default, vetted on Cursor, Claude Code, and Copilot fluency in a voice interview before they unlock bookings. A mid-tier engineer at $1,000 a week can wire all eight surfaces above into your CI in a single sprint, and the 48-hour free trial lets you watch them do it before you pay anything.

The bigger win is not time saved on any single doc. It is that drift stops being a problem. Once doc generation is part of the build, "are our docs current" stops being a question.

What to do next

Pick one surface from the list above and ship it this week. If your API reference is stale, start there. If your incident playbooks live in nine Slack threads, runbooks win. Do not try all eight at once. Start with one pipeline, get it working end-to-end, add the next.

Try Cadence's 48-hour free trial if you want an engineer who already runs this workflow. Book in 2 minutes, use them for two days at no cost, replace any week. Weekly billing means you are never locked in.

If you want help deciding which doc surface to tackle first based on your stack and team size, our Build vs Buy vs Book tool takes a one-paragraph problem statement and gives a recommendation in under a minute.

FAQ

Can Claude generate accurate API documentation from code alone?

Yes for shape (parameters, types, return values) when you point it at the route file plus the type definitions. No for intent, business rules, or rate-limit reasoning. You still review and edit, but the boilerplate is done.

Should I use Claude Code or the Claude API for doc generation?

Claude Code for one-shot terminal runs against a checked-out repo (CLAUDE.md generation, weekly README refresh). The Claude API for doc pipelines (CI jobs, Mintlify-style PR automation) where you want repeatable runs on every merge. Most teams use both.

Will Claude replace technical writers?

Not for thought-leadership docs, novel architecture explanations, or onboarding stories. Yes for the boilerplate 80%: API references, parameter tables, error catalogs, basic runbooks. Good technical writers move up the stack to intent and narrative.

How do I keep Claude-generated docs from drifting?

Run generation as part of CI on PR open, not as a one-shot. Mintlify Workflows, custom GitHub Actions, or Claude Code in a scheduled script all work. Treat docs as build output, not a manual artifact, and drift becomes a build failure instead of a quarterly cleanup project.

Should Claude write code comments?

Use Claude for parameter docstrings and public API surfaces. Skip Claude for inline comments inside function bodies. Those usually capture non-obvious intent the model cannot infer from the code, and a model-written "this loops over the array" comment is worse than no comment.