---
description: Documentation standards for code, architecture, and development decisions
globs: 
alwaysApply: false
---

# Rule: Documentation Standards

## Goal
Maintain comprehensive, up-to-date documentation that supports development, onboarding, and long-term maintenance of the codebase.

## Documentation Hierarchy

### 1. Project Level Documentation (in ./docs/)
- **README.md**: Project overview, setup instructions, basic usage
- **CONTEXT.md**: Current project state, architecture decisions, patterns
- **CHANGELOG.md**: Version history and significant changes
- **CONTRIBUTING.md**: Development guidelines and processes
- **API.md**: API endpoints, request/response formats, authentication

### 2. Module Level Documentation (in ./docs/modules/)
- **[module-name].md**: Purpose, public interfaces, usage examples
- **dependencies.md**: External dependencies and their purposes
- **architecture.md**: Module relationships and data flow

### 3. Code Level Documentation
- **Docstrings**: Function and class documentation
- **Inline comments**: Complex logic explanations
- **Type hints**: Clear parameter and return types
- **README files**: Directory-specific instructions

## Documentation Standards

### Code Documentation
```python
def process_user_data(user_id: str, data: dict) -> UserResult:
    """
    Process and validate user data before storage.
    
    Args:
        user_id: Unique identifier for the user
        data: Dictionary containing user information to process
        
    Returns:
        UserResult: Processed user data with validation status
        
    Raises:
        ValidationError: When user data fails validation
        DatabaseError: When storage operation fails
        
    Example:
        >>> result = process_user_data("123", {"name": "John", "email": "john@example.com"})
        >>> print(result.status)
        'valid'
    """
```

### API Documentation Format
```markdown
### POST /api/users

Create a new user account.

**Request:**
```json
{
    "name": "string (required)",
    "email": "string (required, valid email)",
    "age": "number (optional, min: 13)"
}
```

**Response (201):**
```json
{
    "id": "uuid",
    "name": "string",
    "email": "string", 
    "created_at": "iso_datetime"
}
```

**Errors:**
- 400: Invalid input data
- 409: Email already exists
```

### Architecture Decision Records (ADRs)
Document significant architecture decisions in `./docs/decisions/`:

```markdown
# ADR-001: Database Choice - PostgreSQL

## Status
Accepted

## Context
We need to choose a database for storing user data and application state.

## Decision
We will use PostgreSQL as our primary database.

## Consequences
**Positive:**
- ACID compliance ensures data integrity
- Rich query capabilities with SQL
- Good performance for our expected load

**Negative:**
- More complex setup than simpler alternatives
- Requires SQL knowledge from team members

## Alternatives Considered
- MongoDB: Rejected due to consistency requirements
- SQLite: Rejected due to scalability needs
```

## Documentation Maintenance

### When to Update Documentation

#### Always Update:
- **API changes**: Any modification to public interfaces
- **Architecture changes**: New patterns, data structures, or workflows  
- **Configuration changes**: Environment variables, deployment settings
- **Dependencies**: Adding, removing, or upgrading packages
- **Business logic changes**: Core functionality modifications

#### Update Weekly:
- **CONTEXT.md**: Current development status and priorities
- **Known issues**: Bug reports and workarounds
- **Performance notes**: Bottlenecks and optimization opportunities

#### Update per Release:
- **CHANGELOG.md**: User-facing changes and improvements
- **Version documentation**: Breaking changes and migration guides
- **Examples and tutorials**: Keep sample code current

### Documentation Quality Checklist

#### Completeness
- [ ] Purpose and scope clearly explained
- [ ] All public interfaces documented
- [ ] Examples provided for complex usage
- [ ] Error conditions and handling described
- [ ] Dependencies and requirements listed

#### Accuracy
- [ ] Code examples are tested and working
- [ ] Links point to correct locations
- [ ] Version numbers are current
- [ ] Screenshots reflect current UI

#### Clarity
- [ ] Written for the intended audience
- [ ] Technical jargon is explained
- [ ] Step-by-step instructions are clear
- [ ] Visual aids used where helpful

## Documentation Automation

### Auto-Generated Documentation
- **API docs**: Generate from code annotations
- **Type documentation**: Extract from type hints
- **Module dependencies**: Auto-update from imports
- **Test coverage**: Include coverage reports

### Documentation Testing
```python
# Test that code examples in documentation work
def test_documentation_examples():
    """Verify code examples in docs actually work."""
    # Test examples from README.md
    # Test API examples from docs/API.md
    # Test configuration examples
```

## Documentation Templates

### New Module Documentation Template
```markdown
# Module: [Name]

## Purpose
Brief description of what this module does and why it exists.

## Public Interface
### Functions
- `function_name(params)`: Description and example

### Classes  
- `ClassName`: Purpose and basic usage

## Usage Examples
```python
# Basic usage example
```

## Dependencies
- Internal: List of internal modules this depends on
- External: List of external packages required

## Testing
How to run tests for this module.

## Known Issues
Current limitations or bugs.
```

### API Endpoint Template
```markdown
### [METHOD] /api/endpoint

Brief description of what this endpoint does.

**Authentication:** Required/Optional
**Rate Limiting:** X requests per minute

**Request:**
- Headers required
- Body schema
- Query parameters

**Response:**
- Success response format
- Error response format
- Status codes

**Example:**
Working request/response example
```

## Review and Maintenance Process

### Documentation Review
- Include documentation updates in code reviews
- Verify examples still work with code changes
- Check for broken links and outdated information
- Ensure consistency with current implementation

### Regular Audits
- Monthly review of documentation accuracy
- Quarterly assessment of documentation completeness
- Annual review of documentation structure and organization