Documenting contracts

REQUIRED BACKGROUND: the technical-writing skill (hard rules, truth rules, style).

Overview

A contract document is read by a stranger who cannot see the code and is about to depend on it. Core principle: document the wire, exhaustively, with each detail at its own level; the caller's language is the wire format and domain terms, never the implementation's types. Contract surfaces are reference kind, so the core Reference rule applies: every endpoint, every field, every error.

When to invoke, and not

Invoke when documenting anything machines call or parse: REST and RPC endpoints, message queues and topics, webhooks, CLI commands, file formats. The api-reference.md of a legacy campaign (documenting-legacy-codebases) is this skill's document. Do NOT invoke for internal code interfaces, which the code documents itself, or for configuration references, which belong in config-reference.md under the core Reference rule. Judging whether the contract is well designed is out of scope: this skill documents the contract that exists.

One home versus generated specs

When an OpenAPI or AsyncAPI spec exists, or the code generates one, that spec owns the field tables. The markdown then documents only what the spec cannot say (semantics, side effects, ordering, omitted-versus-null) and links the spec; never hand-maintain field tables beside a generated one; a second home drifts. The catalog below is for the case where no machine spec exists; writing one is not this document's job.

The four detail levels

Each level has its own home; the writer moves detail found at the wrong level into the level that owns it: