Generate Technical Documentation from Code with AI

Verdict

Use AI to draft documentation from named sources at a pinned revision, then make generated references reproducible and examples executable. Ship the docs in the repository with an owner, version, provenance, and drift checks. Do not publish a one-time wiki dump that silently becomes false.

This job begins after the relevant interfaces are understood. For exploratory architecture and call paths, start with understanding an unfamiliar codebase. Compare products in the AI coding-agent guide or CLI coding-agent shortlist.

Decide what is authoritative

Classify each document before prompting:

Code can show what executes. It rarely proves why a trade-off was chosen, which service owns an incident, or what compatibility a customer was promised. Ask maintainers for those facts and label unresolved sections.

Pin scope, audience, and revision

Name the audience, repository revision, supported version, included packages, and excluded internals. Give the agent the source schema, relevant tests, existing terminology, release policy, and documentation style. Prevent source edits during the first draft. Require citations as repository paths and symbols, not invented external footnotes.

At revision 8c31a2f, document the public Refunds API for SDK users.
Sources of truth: openapi/payments.yaml, src/refunds/types.ts,
tests/contract/refunds.test.ts, and examples/refund.sh. Do not edit source.

Produce endpoint purpose, auth, request/response schemas, error table,
idempotency behavior, one runnable curl example, and version/deprecation notes.
Attach source path + symbol/spec pointer to every contract claim. Mark missing
facts as TODO(owner), never infer them. Return changed docs and check commands.

Separate generated reference from curated explanation

Generate stable reference sections directly from the contract where possible. Keep hand-written concepts, decisions, and failure explanations in separate files or protected blocks. Regeneration should replace only generated output. This avoids an agent paraphrasing a schema differently on every run or overwriting maintainer context.

Review examples as product interfaces. Use deterministic IDs, fixed timestamps, fake credentials, and local or sandbox endpoints. Expected output must assert fields that matter rather than copy a large response that no check reads.

Make documentation executable

Add checks proportional to the contract:

• regenerate reference output in CI and fail when git diff --exit-code finds uncommitted drift;
• validate the OpenAPI or schema file and compare it with the release baseline for breaking changes;
• run shell, SDK, and configuration examples against a mock or test environment;
• compile code snippets and verify referenced symbols, anchors, and internal links;
• require documentation changes when contract files or public types change.

These checks catch specific drift. They do not prove prose clarity or complete coverage. A human reviewer still owns audience fit, security guidance, migration implications, and release wording. Use the AI pull-request review workflow for evidence standards.

Hacker News user hitchstory described generating how-to documentation from domain-language tests and combining it with explanatory material that changes less often. That is an individual implementation report, not proof that generated docs never drift. The durable pattern is narrower: derive checkable reference material from executable inputs and review the remaining prose.

Ship a versioned documentation artifact

A concrete repository deliverable might include:

# docs/manifest.yml
documents:
  - path: docs/api/refunds.md
    audience: sdk-users
    source: openapi/payments.yaml#/paths/~1refunds
    source_revision: 8c31a2f
    contract_version: 2.3.0
    owner: payments-platform
    examples: [examples/refund.sh]
    checks: [make openapi-check, make docs-examples, make docs-links]

The same pull request should contain the generated reference diff, curated migration notes, runnable example, validation configuration, and an explicit deprecation window when policy requires one. Version the public contract according to the project’s published compatibility rules; Semantic Versioning is useful only when the project actually follows it.

Choose the agent by documentation loop

Pricing and limits checked October 2, 2026.

When docs expose a bug or ambiguous contract, stop the writing pass. Move the behavior change into a separately scoped implementation task, protect it with maintainable tests, then update the documentation from the accepted contract.

Sources & further reading

• Claude Code overview
• Claude pricing and usage limits
• Codex pricing and usage limits
• Codex code review
• Aider documentation workflow and repository guidance
• Aider linting and testing
• OpenAPI Specification
• Semantic Versioning specification
• Community discussion of executable documentation