Documentation-First Development

Every Feature Needs

1. RFC document before implementation
2. API documentation (OpenAPI)
3. User-facing documentation
4. Code comments for non-obvious logic
5. CHANGELOG entry
6. Migration guide (if breaking)

README Requirements

• Project description (what + why)
• Quick start guide (< 5 minutes)
• Architecture overview with diagram
• Environment setup instructions
• Common tasks and commands
• Troubleshooting section
• Contributing guidelines

Code Documentation

• JSDoc for all exported functions
• @example tags with working examples
• @throws tags for error conditions
• @see tags for related functions
• Inline comments for complex algorithms

API Documentation

• Every endpoint documented in OpenAPI
• Request/response examples
• Error response catalog
• Authentication requirements
• Rate limiting details

Decision Records

• Use ADR format (context, decision, consequences)
• Number sequentially
• Never delete, only supersede
• Review quarterly