documentation-templates

A good README starts with a title and one-line description, followed by a quick start section runnable in under five minutes. Then add features, a configuration table, links to detailed docs, contributing guidelines, and license information.

Each endpoint should document the HTTP method and path, a parameter table with name, type, required status, and description, plus response codes and a concrete request-response example. Keep each endpoint self-contained for easy reference.

Comment the why behind business logic, complex algorithms, non-obvious behavior, and API contracts. Avoid commenting obvious code, every line, or implementation details that are self-explanatory from the code itself.

An ADR is a short document capturing a significant technical decision with four parts: status, context explaining why the decision was needed, the decision itself, and consequences including trade-offs. It preserves reasoning for future maintainers.

Use a clear H1-H3 heading hierarchy, JSON or YAML examples for data structures, Mermaid diagrams for flows, and self-contained sections. Adding an llms.txt file listing core files and key concepts helps AI crawlers and agents index your project.