AI for Developer Documentation That Stays Current

AI for developer documentation is useful when the model is a compiler of sources you already trust, not a novelist. Ask it to "write our API docs" with an empty context window and you will ship endpoints that do not exist, auth flows that never shipped, and onboarding guides that contradict production. This article is the daily workflow we use: generate from OpenAPI, proto files, runbooks, and merged PRs; refuse undocumented claims; and turn stable curricula into a self-hosted email series instead of a decaying Confluence page.

Key Takeaways:

• Generate docs from contracts and code, then have humans approve tone and examples.
• Ban undocumented endpoints: if it is not in OpenAPI or the handler, it does not go in the README.
• Keep runbooks next to alerts so AI debugging and docs share the same source of truth.
• Use Cadensend when the artifact is a learning series, not a marketing blast — open source, self-hosted, no hosted signup.
• Scan sample snippets for secrets with Ocherfort before they land in public docs.

Table of Contents:

• The Documentation Failure Mode AI Makes Faster
• Source-Grounded Generation
• A Docs Pipeline You Can Run Every PR
• Runbooks, Not Novels
• Onboarding Curricula vs Wiki Pages
• Reviewing AI-Written Docs Like Code
• Frequently Asked Questions

The Documentation Failure Mode AI Makes Faster

Developer documentation dies in two ways: it is never written, or it is written once and then lies. AI accelerates both. Teams generate a beautiful Getting Started in an afternoon, then never regenerate it when the auth header changes from X-API-Key to a bearer token.

The failure is not "the model is dumb." The failure is ungrounded generation. Language models complete the shape of docs they have seen: a base URL, a curl, a 200 JSON blob. They will invent a GET /v1/users/me because every SaaS has one. Yours might be GET /session with a cookie. New hires will debug the hallucination for a day and then stop trusting docs entirely.

Contrast that with how OpenAPI and Protobuf already describe your surface. HinterBuild's backend and API engineering practice treats the spec as the product. AI should be the pretty-printer and the example factory, not the architect.

If you need protocol-level help connecting assistants to live systems, start with MCP explained with real code examples. MCP is how an assistant can read the spec from disk or a registry instead of guessing. For the day-to-day tool loop, see MCP tools for daily development.

Source-Grounded Generation

Short answer: only generate a paragraph if you can point at a file, a spec path, or a merged commit that supports it.

Grounding sources that work in practice:

The logging column matters. If production logs request_id and docs say correlationId, every new engineer will grep the wrong string during an incident. Align docs with structured logging field names, and keep those names in your observability dashboards.

A generation prompt that refuses fiction:

You are writing developer documentation. You may only state facts present in the attached sources.
If a fact is missing, write TODO(source-needed) and stop. Do not invent paths, headers, status codes, or SDK methods.
Audience: engineers integrating our HTTP API.
Sources: openapi.yaml, README snippets, the two attached tests.
Output: markdown with a curl example per operation, using the real operationId.

When the surface is an LLM streaming endpoint, examples must show abort, backpressure, and partial JSON — not a fake synchronous 200. Use streaming LLM responses in production as the engineering companion, and keep the public docs thinner than the internal runbook.

For assistants that live in the terminal, attach files rather than pasting half a spec. That is the same muscle as terminal AI CLI workflows. If you are choosing a hosted vs local model for internal wikis, local vs cloud AI coding assistants covers the data-residency trade.

A Docs Pipeline You Can Run Every PR

Treat docs like codegen. A human still merges, but CI should fail when examples rot.

Minimum pipeline:

1. Extract. On each PR that touches handlers or proto, regenerate the "API reference" section from the spec. Do not regenerate narrative pages automatically.
2. Example test. Every curl or SDK snippet in docs/ runs in CI against a sandbox or a recorded cassette. If the snippet needs a secret, it is a leak — scan with Ocherfort (config and pipeline gates) so sk-live-... never ships in a markdown fence.
3. Link check. Internal links to /blog/... and service pages are cheap; broken ones train people to ignore docs.
4. Diff review. The PR description should say what the spec changed, not "updated docs." Pair this with PR descriptions reviewers actually read.

# run ocherfort (or equivalent) on the docs path in CI
- name: scan docs for secrets
  run: ocherfort scan --path docs --gate config

Ocherfort is a local-first repo security CLI: it orchestrates checks, maps findings to standards, and writes evidence under .ocherfort/runs/. It is not a cloud dashboard and not a substitute for specialist scanners. For docs, you want the boring win — no keys in samples — plus an artifact you can attach to the PR.

Estimation of the docs ticket belongs in the same system you use for product work. If you estimate with AI, score "regenerate reference" as small and "rewrite mental model / architecture" as large. Models under-price the second because the tokens look similar.

Keep MCP in this pipeline if your editors already speak it. A filesystem MCP server that can only read openapi.yaml and docs/ is safer than a general shell. Details live in the MCP tutorial. Compare assistant products in OpenClaw vs Claude Code if the question is "which tool writes the first draft in our repo."

Runbooks, Not Novels

AI for developer documentation shines on runbooks because the shape is constrained: symptom, checks, commands, rollback. It fails on "our philosophy of platform engineering" because there is no failing test for vibes.

Write runbooks as checklists next to the alert. Then let AI:

• Convert a messy Slack incident into a first-draft runbook from the redacted timeline
• Normalize command syntax across services
• Cross-link the dashboard URL and the owner

Do not let it invent a kubectl flag you have never used. After the production debugging playbook, the runbook should cite the same trace_id field your collectors emit. If you stream model output, the runbook must include "client disconnected / incomplete SSE" as a first-class symptom, not an afterthought.

Observability copy is documentation. Dashboard names, label keys, and SLO text should be generated from the same repo that defines the monitors. HinterBuild's observability and monitoring work includes runbook-linked alerts for this reason: an alert without a doc is a page without a procedure.

A small template we keep in-repo:

## Symptom
HTTP 502 on POST /v2/checkout, EU only

## Checks
1. Trace in Tempo by `trace_id`
2. Deploy SHA vs last green
3. Inventory-svc deadline errors in Loki

## Mitigate
- Disable `payments.retry_v2` flag
- Do not restart all pods

## Rollback
`argo rollback payments-api`

Ask the model to fill Checks from attached Grafana JSON or alert YAML. If those files are missing, the honest output is TODO(source-needed).

Onboarding Curricula vs Wiki Pages

Wikis rot because they try to be complete. New hires need a sequence: day-one access, day-two local run, day-three first PR, week-two on-call shadow. That is a curriculum, not a page tree.

This is the correct job for Cadensend. Cadensend is an open-source, MIT-licensed, self-hosted email curriculum engine. You give it a learning goal and your sources (runbooks, ADRs, OpenAPI). It plans modules, writes issues with citations back to those sources, and delivers on a schedule, exactly once. It is not a marketing suite, not a CRM, and there is no hosted signup — which is what you want for internal onboarding.

Use Cadensend when:

• You are onboarding engineers onto a stack (Go services, our LLM gateway, our MCP servers)
• You want a seven-issue series instead of a 40-page Notion dump
• Citations must point at files you supplied, not at the public internet

Do not use it as a bulk sender or an autonomous research agent. Pair the series with a hands-on week such as learn a new framework in one week with AI and a personal AI coding journal so the curriculum is not one-way email.

Daily habits still matter. Standup prep with AI should pull "docs PR merged" as real work. Ticket estimates should include doc follow-through or the API will ship mute.

For the company story and how we staff this, and to book a working session on docs pipelines, those two pages are the human path. The engineering path is spec-first APIs via backend engineering.

Reviewing AI-Written Docs Like Code

Reviewers should reject documentation the same way they reject tests that never fail.

Block the merge if:

• An endpoint, header, or status code cannot be clicked through to the spec
• Examples contain real-looking secrets or production hostnames
• The page describes a future design as current tense
• Internal links 404, including sibling guides like terminal AI CLI workflows
• Streaming or async behavior is documented as a single JSON response

Approve faster if:

• The diff is mechanical (spec regen)
• Examples ran in CI
• The narrative change is a single paragraph with a cited ADR

Human voice still matters. AI prose defaults to "simply" and "just." Delete those. Developers using AI every day are allergic to tutorial condescension. Match the tone of OpenClaw vs Claude Code: trade-offs, not slogans.

Finally, version the prompts you use to generate docs, the same way you version product prompts. When a regen goes sideways, you want to know whether the spec changed or the prompt did. That is boring, and it is why the docs stay true.

Changelog discipline

Changelogs are documentation, and AI is unusually bad at them unless you constrain the diff. "Various improvements" is not a changelog. Feed git log plus the OpenAPI diff and require each bullet to name a path or a flag. If you prep standups with AI, reuse that same artifact list: a merged docs PR is yesterday's work, not a footnote.

For streaming or agent APIs, the changelog must mention backward-incompatible observable behavior: heartbeat intervals, abort semantics, tool-call ids. Those are the details client authors actually break on. HinterBuild's backend and API engineering reviews treat a silent change to error JSON as a breaking change even when the HTTP status stays 400.

When not to generate

Skip AI for:

• Legal terms, data-processing addenda, and anything that must survive a lawyer
• Security advisories until a human has verified the affected versions
• "Vision" pages that are supposed to be opinionated; a model will sand them down to mush
• Incident customer statements — same rule as AI debugging: symptoms and next update only

Generate for:

• Reference tables from specs
• Migration checklists from merged PRs
• First drafts of tutorials that you will run line by line
• Internal onboarding sequences you will host yourself with Cadensend

If your team lives in the terminal, keep the generator next to make docs rather than in a chat tab. That habit is documented in terminal AI CLI workflows. If the assistant needs live repo context, prefer MCP file tools with a narrow root over pasting half the monorepo; see MCP tools for daily development.

Frequently Asked Questions

Can I let AI write our entire developer portal?

No. Let it draft reference pages and first-pass tutorials from specs and tests. Humans own information architecture, support promises, and anything legally binding. Ungrounded portals become a support queue.

How do I keep AI-generated docs from inventing endpoints?

Constrain the context to OpenAPI or proto, and instruct the model to emit TODO(source-needed) when a fact is missing. Add CI that greps docs for paths not present in the spec.

Where should secrets in examples go?

Nowhere. Use fake tokens with an obvious prefix, and scan docs/ with Ocherfort in CI. If an example needs a real credential, it belongs in a local secrets manager, not in markdown.

When is an email curriculum better than a wiki?

When the job is sequenced learning — onboarding, a framework rollout, or on-call training. Cadensend turns a goal plus your sources into a cited series you host yourself. Wikis remain useful as a lookup index, not as a teacher.

Should docs live in the same repo as the API?

Yes for reference and runbooks. That is how PRs keep them honest. Narrative guides can live nearby, but they should still CI-check links and examples.

How does MCP help documentation workflows?

MCP lets the assistant read the spec, repo files, and (carefully) internal tools through a standard protocol instead of a one-off plugin. See MCP explained with real code. Do not give a docs agent unrestricted shell.

Conclusion

• Ground every sentence in a spec, test, or runbook.
• Automate reference regen; review narrative like code.
• Scan examples for secrets; keep field names aligned with logs and traces.
• Use a self-hosted curriculum engine when the artifact is a learning series.

AI for developer documentation pays off when it is a printer for truth you already have. If you need that wired into APIs and observability, contact HinterBuild or read about the team.

Related Articles

• AI debugging production errors
• AI coding journal learning series
• Learn a new framework in one week with AI
• PR descriptions reviewers actually read
• MCP tools for daily development
• Use AI to estimate tickets
• MCP explained with real code examples
• Structured logging: stop using fmt.Println

Author: HinterBuild Engineering Team. Connect with Abdul Sami on LinkedIn.