What others depend on.
WHAT TO DOCUMENT FOR EVERY ENDPOINT OR FUNCTION
What it does What it requires What it returns What errors it can produce
Any constraints: limits, permissions, side effects
WHY ERRORS SPECIFICALLY
Callers must handle them, and undocumented errors are handled badly or not at all.
WHAT TO GENERATE
Reference documentation from the code or a specification.
WHY
Manually maintained references diverge immediately.
WHAT A SPECIFICATION PROVIDES
A machine-readable contract, usable for generating documentation, clients and tests.
WHAT TO INCLUDE BEYOND REFERENCE
Examples of actual use An explanation of authentication Versioning and deprecation policy
WHY EXAMPLES MATTER MOST
They are what people actually use.
WHAT TO DOCUMENT ABOUT CHANGES
What changed, when, and what consumers must do.
WHAT TO NEVER DO
Change a published interface without notice Deprecate without a timeline and an alternative
WHAT TO KEEP
Documentation for versions still in use.
