Documentation Writing Standards

# Documentation Standards ## README Structure Every project README must include (in order): 1. Project name + one-line description 2. Quick start (3 commands max to get running) 3. Prerequisites (runtime, tools, env vars) 4. Architecture overview (high-level diagram or description) 5. Development workflow (build, test, deploy) 6. Contributing guidelines (or link to CONTRIBUTING.md) ## Code Comments - Comment WHY, never WHAT. The code says what; comments say why. - Delete commented-out code. Git remembers. - Use TODO with a ticket number: `// TODO(GP-123): handle pagination`. - Use JSDoc for public APIs: params, returns, throws, examples. - No comments on self-explanatory code. `// increment counter` on `count++` is noise. ## API Documentation - Document every public endpoint with: description, params, response, errors. - Include request/response examples with realistic data. - Document rate limits, auth requirements, and pagination. - Keep docs next to code (co-location), not in a separate wiki. ## Architecture Decision Records (ADRs) When making a significant technical decision: ```markdown # ADR-NNN: Title ## Status: Accepted | Deprecated | Superseded by ADR-XXX ## Context What situation or problem prompted this decision? ## Decision What did we decide and why? ## Consequences What are the positive and negative effects? ``` ## Changelog - Use Keep a Changelog format. - Categories: Added, Changed, Deprecated, Removed, Fixed, Security. - Link to PRs/issues for traceability.