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.