documentation

A good README explains what the project is and why it exists, provides a quick start achievable in under five minutes, and covers configuration, usage, and contributing guidelines. Lead with the most useful information rather than burying it.

API documentation should include an endpoint reference with request and response examples, authentication details, error codes, rate limits, pagination behavior, and SDK examples. Concrete examples matter more than abstract descriptions.

A runbook is operational: it lists prerequisites, step-by-step procedures, rollback steps, and escalation paths for a specific task. An architecture doc explains context, goals, high-level design, key decisions, and trade-offs.

Treat outdated docs as worse than no docs and update them alongside code changes. Link to other documents instead of duplicating content, so each fact lives in exactly one place.

Write an onboarding guide when new team members need environment setup, an overview of how systems connect, walkthroughs of common tasks, and contacts for specific areas. A README covers a single project, not the whole team landscape.