API Docs & Architecture Decision Records

Option B is the professional standard. It includes every required field: HTTP method + path, a plain-English summary, auth requirements with scope, path parameter type/requirement, request body note, multiple response codes with meanings, and operational notes (rate limiting, privacy — non-obvious but important). Option A is two sentences — missing all the detail developers need. Option C has wrong status code ("200" for an async operation that queues an email should be "202"), mixes fields informally. Option D uses a non-versioned path, returns "ok/error" (not proper HTTP codes), and is missing all parameter descriptions.

Option B follows Keep a Changelog exactly. The format is ## [version] — YYYY-MM-DD with categorised sections (Added, Changed, Fixed, Deprecated). Each entry is a specific, actionable item with a ticket reference where relevant. The Deprecated section gives a removal timeline and the migration path. Option A is useless — "see commits" forces developers to read the git log themselves. Option C is bullet notes without dates, version headers, or categorisation. Option D is a marketing press release — entertainment, not documentation. Technical changelogs are read by developers who need exact information, not enthusiasm.

Option B is the professional standard. It has a numbered title, status with acceptance date, a Context section explaining what was evaluated and why this decision was needed (the forces at play), a clear Decision statement, and a Consequences section with both positive (✓) and negative (✗) trade-offs explicitly called out. This makes the decision reviewable and reversible by future engineers. Option A gives no reasoning. Option C is good prose but missing the formal structure — no numbered ID, no status, trade-offs are implicit. Option D has the right headers but no detail — "needed a database" is not context, and the consequence descriptions are too vague to act on.