api-documentation

原文涵盖的主题

• API documentation
• 1. Generate the mechanical parts
• 2. Document each parameter properly
• 3. Document errors as thoroughly as successes
• 4. Show real, complete, runnable examples
• 5. Cover the operational contract
• 6. Organise for search, not for reading
• Keeping it true

Reference documentation is not read; it is searched. Someone arrives mid-task with a specific question — what does this return, what happens when it fails, is this required, and leaves as soon as they have the answer. Optimise for that. Completeness beats narrative, and the questions people actually have are rarely the ones the happy-path example answers. Signatures, types, parameter lists, and status codes should come from the code — OpenAPI from annotations, docstrings extracted, CLI help generated. Anything hand-maintained drifts, and wrong reference documentation is worse than none because it is believed. Hand-write only what cannot be derived: why, when, what happens on failure, and the constraints the type system does not express. Done when: no fact appears in both the code and the docs, maintained separately. A name and a type are not documentation. For each parameter: What it means, in domain terms Required or optional, and the default if optional — the default is the most frequently looked up fact and the most frequently missing Valid values or range. For an enum, all of them Format, where ambiguous — is a date a Unix timestamp, ISO 8601, or a date-only string? What happen

这里只展示节选，请以完整原文和当前要求为准。