Technical Documentation Checklist

List the services, endpoints, or modules in scope for this docs cycle. Pull the merged PRs since the last docs release from GitHub and flag any user-visible behavior changes, new endpoints, or deprecations that need coverage.

Pin the audience: integrating backend engineers, frontend SDK consumers, on-call SREs, or end-user admins. The same feature reads differently for each — an API reference for engineers vs. a UI walkthrough for admins.

Public docs are subject to legal/marketing review and may need WCAG 2.1 AA review for accessibility. Internal-only docs (Backstage, Confluence) skip those steps but still need access controls confirmed.

Refresh the C4 or Mermaid diagram in the repo so it reflects current services, queues, and data stores. Diagrams that drift from production are worse than no diagram — onboarding engineers chase ghost services.

List runtime versions (Node 20, Python 3.12, Postgres 16), key frameworks, and infrastructure (EKS, Terraform, Datadog). Pin exact versions where they matter — "Postgres 16" not "Postgres".

Add or update Architecture Decision Records (ADRs) for any significant patterns introduced this cycle — async messaging, multi-tenancy strategy, caching layer. Title, context, decision, consequences. The point is to record the trade-off so future engineers don't relitigate it.

Specify minimum versions for Docker, Node, Python, and any CLI dependencies. Note supported OSes (macOS 13+, Ubuntu 22.04+, WSL2). Missing prereqs are the #1 reason new-engineer Day 1 environment setup blows past lunch.

Spin up a fresh container or VM with no existing creds, follow the README top-to-bottom, and time it. If it doesn't run green in under an hour, the docs are wrong. Common gotchas: missing `.env.example`, unstated AWS SSO profile, brew formula renamed.

Update the README, the bootstrap script, and the `.env.example` to cover whatever broke. Re-run the clean-machine verification before moving on — fixes that aren't re-tested tend to introduce new gaps.

Run the OpenAPI/Swagger generator against the current main branch. Diff against the published spec — any new, removed, or breaking-changed endpoints need release-note entries and possibly a deprecation timeline.

Each endpoint needs a curl example, a 2xx response body, and at least one error response (400 or 422). Use realistic payloads — not `{"foo": "bar"}`. Pull from the Postman collection or e2e fixtures so examples stay in sync with reality.

Cover the OAuth scopes, API key formats, and per-tier rate limits (e.g., 100 req/min for free, 1000 req/min for pro). Note the 429 response shape and Retry-After header behavior. Integrators hit rate limits before they hit auth bugs.

For each breaking change, document the old behavior, the new behavior, the migration path, and the sunset date for the old endpoint. Follow semver: breaking changes only in major versions.

Write a side-by-side before/after for each affected endpoint, with code samples in the SDKs you publish (JS, Python, Go). Set a deprecation window of at least 90 days and announce it in the changelog and via email to API customers.

Every exported function, class, and module on the public surface needs a docstring covering purpose, params, returns, and raised exceptions. Run the doc linter (e.g., pydocstyle, jsdoc-lint) and resolve warnings on changed files.

README covers what the service does, how to run it, and where to find deeper docs. CONTRIBUTING covers branch naming, PR size budget (target under 400 lines), CODEOWNERS, and the test commands. Keep it current — stale CONTRIBUTING is why first-PR engineers get yelled at.

Spell out the unit, integration, and e2e commands (`pytest`, `npm test`, `playwright test`). Include how to attach a debugger, how to run a single test, and how to seed local fixtures. Mention any flaky-test workarounds and where to find the flaky-test dashboard.

Pick the top 5 user tasks from support tickets and write step-by-step guides for each. Task-based docs ("Configure SSO with Okta") outperform feature-based docs ("The SSO Settings Page") because users come with a goal, not a curiosity.

Use the staging environment with realistic seeded data (no "test test" usernames). Crop screenshots to the relevant UI region, redact any PII. Keep Loom clips under 90 seconds — long videos get skipped.

Pull the top inbound questions from Zendesk or Intercom over the last 30 days. Each FAQ entry covers symptom, cause, and fix — not just symptom and "contact support".

Run axe or Lighthouse against the published docs site. Confirm alt text on all images, sufficient color contrast, keyboard navigation through nav and code blocks. Required for WCAG 2.1 AA and the EU Accessibility Act.

Merge the docs PR, deploy to the public docs site (Docusaurus, GitBook, or Mintlify), and tag the docs repo with the matching release version. Post the changelog summary to #engineering and to the customer-facing changelog.