Skip to main content

Single-Repository Documentation Checklist

Use this checklist for one-app-one-repo projects.

1) Core repository page (required)​

  • Purpose section explains business/platform role.
  • Scope section defines what the repository owns and does not own.
  • "What this app/service does in production" section is concrete (not generic).
  • Primary user/system workflows are listed as real end-to-end flows.
  • Setup/run references point to source docs and required runtime environment.

2) Interfaces, dependencies, and runtime​

  • Identify main inputs/outputs (API, jobs, events, files, queues, telemetry).
  • List critical upstream dependencies and downstream consumers.
  • Note external systems (payments, messaging, cloud services, IoT, observability, etc.).
  • Runtime behavior section exists (request/worker/scheduler model as applicable).
  • Failure modes section exists with practical diagnostics hints.
  • Change-impact map exists ("if X changes, verify Y/Z").

3) Evidence threshold (required)​

  • At least 5 concrete facts are traceable to source artifacts (routes, modules, env vars, jobs, configs).
  • At least 2 concrete workflows are documented end-to-end.
  • At least 3 concrete failure/edge cases are documented.
  • Source-of-truth pointers are included (specific files/paths in source repo).

4) Repo-type extensions (choose one)​

  • Frontend-heavy repo: route surface, UX-critical workflows, and realtime behavior are documented.
  • Backend-only repo: endpoint contracts (inputs/outputs), API/job boundaries, datastore/external data-source usage, and operational run behavior are documented.
  • Shared-library repo: consumer contract (how apps import/use it), compatibility/change-impact guidance, and versioning/release expectations are documented.
  • Automation/ops repo: execution entrypoints, environment/tooling prerequisites, artifact outputs, and failure/rollback considerations are documented.

5) Quality gates before merge​

  • Repository page is linked in Repositories overview.
  • Sidebar order conventions are preserved (nxt-*, then lorawan-*).
  • Content is practical and avoids stale boilerplate/meta-only status text.
  • npm run build passes.