documentation-templates

A good README starts with a one-sentence description, then a Quick Start section with copy-paste commands, followed by requirements, project structure, environment variables, and test instructions. The first 30 seconds of reading determine whether someone adopts your project.

Document each endpoint with its purpose, a request body schema showing types and constraints, a response table mapping status codes to meanings and bodies, and a working curl example. Cover success, validation failure, and conflict cases.

Comments should explain why code exists, not what it does. Always comment non-obvious business rules, workarounds for library bugs, performance decisions that look premature, and magic numbers with their justification.

A runbook is an operational document for on-call engineers listing symptoms, likely causes, investigation commands, resolution steps, and escalation paths. You need one for any production service that may fail outside business hours.

Keep a CODEBASE.md with tech stack and conventions, an ARCHITECTURE.md with system boundaries and data flow, and @purpose comments on complex functions. Also mark auto-generated files that should not be edited directly.