API and technical documentation

The test for technical documentation is unforgiving and easy to apply: can someone succeed without asking anyone? Every question a developer has to ask is a documented gap with a support ticket attached, and the cost is paid every time a new person integrates.

Two things separate documentation that passes from documentation that does not, and neither is writing quality. Working examples, and errors treated as seriously as successes.

The operational shape

Trigger. An API change — a new endpoint, a changed response shape, a deprecation.

Reads. The API itself. Voice, lightly.

Cadence. Per change, coupled to the release. Documentation that ships separately from the code it describes is documentation that is wrong between the two.

Gate. Notify after, accuracy-checked rather than voice-checked. A well-written page describing the wrong response shape is worse than a plain one that is right.

What good looks like

Every endpoint has an example that runs. Copied, pasted, executed, and it works. Examples with placeholder values that were never tested are the most common defect in technical documentation and the most damaging, because they fail after the reader has committed effort.

Errors are documented as thoroughly as successes. Every error code, what causes it, and what to do. Developers spend most of an integration on the unhappy path, and it is the part almost always left as an afterthought.

It says what changed and when. Deprecations with dates, and migration paths that are actually walked through. A deprecation notice with no migration path is an announcement of a problem.

Concepts are separated from reference. Reference material answers "what does this endpoint do." Conceptual material answers "how does this system think." Interleaving them produces pages that are too long to scan and too shallow to learn from.

Authentication is first and complete. It is the first thing every integrator does and the most common place they get stuck.

When it goes stale

This is the only capability whose staleness is instantaneous and mechanically detectable. The moment a deploy changes a response shape, the documentation describing it is wrong — not gradually, not arguably, but immediately and checkably.

That property is an advantage if the system uses it. Generated reference documentation cannot drift, because it is derived from the thing it describes. What remains hand-written — the guides, the concepts, the examples — is the part that needs a release-coupled review, and the part where staleness hides.

Three triggers worth naming. A response shape changed and the reference was not regenerated. An example stopped running, which is testable automatically and almost never tested. And a concept guide describes an architecture that has moved, which is the slowest failure and the one that misleads most deeply.

What it feeds

• Support deflection — the outcome this capability is judged on
• Developer evaluation — documentation is what a technical buyer reads before talking to anyone, and it is read as a proxy for engineering quality
• The knowledge base — the boundary is the reader, not the subject