20. Vibe Coding for Documentation (That Doesn't Lie)

What this section is for

AI is great at writing documentation that sounds correct. That’s the problem: it can be confidently wrong.

This section teaches “docs that don’t lie” workflows—how to use AI to draft and update docs while grounding everything in the actual code, tests, and interfaces.

Why AI-written docs often lie

Docs drift happens because:

• code changes faster than docs,
• interfaces have implicit behavior not stated in docs,
• AI fills gaps with plausible assumptions,
• teams don’t have a process to keep docs updated.

The fix is procedural: ground docs in structure and treat docs as artifacts that are verified.

Principles for truthful documentation

• Ground in code structure: file maps, public APIs, entrypoints.
• Prefer examples and contracts: inputs/outputs, error behaviors, schemas.
• Make unknowns explicit: if it’s not in code/tests, mark as unknown.
• Automate where possible: docs as a build artifact.
• Review docs like code: diffs, PR review, and verification.

A practical docs workflow with AI

1. Create a file map: what modules exist and what they do.
2. Identify public contracts: CLI commands, API routes, function signatures, schemas.
3. Draft docs from contracts: examples, edge cases, error behavior.
4. Verify: spot-check against code/tests; run commands.
5. Automate updates: generate docs in CI where possible.
6. Version behavior artifacts: prompts/schemas as files with versions.

Section 20 map (20.1–20.5)

• 20.1 Generate docs from code structure
• 20.2 “Docs as a build artifact” workflow
• 20.3 API docs: examples, edge cases, and error contracts
• 20.4 README that gets people to “hello world” fast
• 20.5 Changelogs and migration notes with AI assistance

Where to go next

• Start with 20.1
• Reference: versioning prompts