20.2 "Docs as a build artifact" workflow

Goal: keep docs updated automatically

Docs drift because updating docs is optional work. The “docs as a build artifact” workflow makes docs updates part of the normal build pipeline.

The goal is:

• docs are generated/validated in CI,
• docs changes show up as diffs,
• docs stay close to the code’s real behavior.

Docs as a build artifact (what it means)

It means you treat documentation outputs like build outputs:

• generated docs are produced deterministically from sources,
• changes are reviewed in PRs,
• the build fails if docs are inconsistent (optional but powerful).

Examples of “sources”:

• API schemas (OpenAPI, JSON schema)
• typed interfaces and docstrings
• CLI help output
• tests and examples

Source-of-truth strategy

Pick a clear source of truth:

• APIs: request/response schemas and tests
• CLI: help output + README examples + tests
• AI behavior: prompt + schema versions

The goal is “docs reflect contracts,” not “docs reflect intentions.”

A practical workflow (local + CI)

1. Write docs sources: schemas, docstrings, examples.
2. Generate docs locally: produce markdown/HTML outputs.
3. Commit generated docs (optional): or publish them in CI.
4. CI gate: verify docs generation is up to date.

Even if you don’t fully automate generation, you can automate verification (“docs must be regenerated”).

Docs gates (prevent drift)

Examples of lightweight gates:

• CI checks that generated docs match committed docs
• CI runs a script that validates schemas and example payloads
• CI verifies README quickstart commands (smoke test)

These gates keep docs from becoming stale silently.

Where AI fits (and where it shouldn’t)

AI is great for:

• drafting explanatory text from a file map and contracts
• generating example payloads from schemas (then you validate)
• rewriting docs for clarity without changing meaning
• drafting changelogs and release notes (then you review)

AI is bad for:

• inventing undocumented behavior
• guessing API contracts without evidence
• describing “best practices” instead of your system’s real behavior

Where to go next

• 20.3 API docs
• 20.4 README quickstart