Skip to content
Back to AI Coding

Documentation Generation

Generate user-facing docs from code + intent; keep them in sync via a regen check.

Docs & RefactorIntermediate

Why

GitHub's 2024 survey found 81% of developers expect AI tools to become more integrated in documenting code over the next year, the highest of any workflow. Docs drift from code the moment they're written.

Generating them from code + a small intent prompt, and failing CI on drift, keeps docs accurate with no manual toil.

When

Use for reference docs (API, CLI, config) that mirror code. Skip for conceptual/prose docs.

How

1. Pick a doc that mirrors code (API reference, CLI usage). 2. Prompt: "generate docs from these files; one section per export; include types + examples". 3. Commit; add a CI check that regenerates and fails on diff. 4. Review the generated diff in PRs. 5. Hand-edit only the intro/examples, not the reference body.

Example

Prompt: "@folder src/api generate API reference; one section per route; method, path, body schema, response schema, example request/response." Output: docs/api.md with 12 sections. CI regen check fails if a route is added without updating docs.

Common Problems

  • ⚠Error: Cannot find module 'xxx' after refactor → re-run `npm install` and `npx tsc --noEmit`; refactors often drop or rename imports.
  • ⚠Error: "Cannot read properties of undefined" after refactor → run the test suite (`npm test`) to catch behavior changes; refactor must be behavior-preserving.
  • ⚠Error: Docs drift: example no longer runs → execute examples in CI (`npm run docs:check`); tested examples never drift.

Best Practices

  • ✓Fail CI if committed docs differ from a fresh regen.
  • ✓Keep hand-written content (intro, guides) separate from generated reference.
  • ✓Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved.

FAQ

What is Documentation Generation?

Generate user-facing docs from code + intent; keep them in sync via a regen check. It helps developers quickly grasp the core value and use cases of Documentation Generation.

How do I get started with Documentation Generation?

To get started with Documentation Generation, focus on these points first: Pick a doc that mirrors code (API reference, CLI usage).

What are common mistakes with Documentation Generation?

Common mistakes when using Documentation Generation include: Error: Cannot find module 'xxx' after refactor → re-run `npm install` and `npx tsc --noEmit`; refactors often drop or rename imports.; Error: "Cannot read properties of undefined" after refactor → run the test suite (`npm test`) to catch behavior changes; refactor must be behavior-preserving.; Error: Docs drift: example no longer runs → execute examples in CI (`npm run docs:check`); tested examples never drift..

What are the best practices for Documentation Generation?

Best practices for Documentation Generation include: Fail CI if committed docs differ from a fresh regen.; Keep hand-written content (intro, guides) separate from generated reference.; Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved..

How do I learn more about Documentation Generation?

Start with the official docs, then search real-world examples on GitHub. Validate patterns in a small scratch repo before applying them to production code.