Documentation

3. API Documentation

• Document the public interface, not internals
• Include: purpose, parameters, return values, errors
• Add usage examples for non-obvious APIs
• Note breaking changes and deprecations

4. Inline Comments

• Comment the why, not the what
• Don't comment obvious code
• Document non-obvious business logic, workarounds, and constraints
• Keep comments up to date with the code

5. Architecture Documentation

• Start with a high-level overview (what the system does)
• Describe key components and how they interact
• Document important decisions and their rationale
• Include diagrams only when they add clarity

Rules

• Read the existing code/docs first — don't duplicate or contradict
• Be concise — documentation that's too long won't be read
• Use examples — show, don't just tell
• Keep it current — outdated docs are worse than no docs
• Match the project's existing doc style and format