# Documentation Management

## CLAUDE.md Content Policy

**CLAUDE.md should only contain operational requirements:**
- Environment setup (PYTHONPATH, GPU mutex)
- Execution requirements (how to run tests/benchmarks)
- Quick configuration reference
- Documentation index (links to detailed docs)

**Technical details should go to docs/:**
- Architecture and design explanations
- Implementation details and code flows
- Debugging techniques
- Memory analysis and profiling
- Algorithm explanations

## When Adding New Technical Content

Follow this workflow:

### Step 1: Analyze and Document

If doing technical analysis (e.g., memory profiling):
1. Calculate theoretical values using formulas
2. Run actual tests to measure real values
3. Compare theoretical vs actual (expect < 10% error for valid models)
4. Document findings with both theory and empirical validation

### Step 2: Create/Update docs/

Create a new doc or update existing one in `docs/`:
```
docs/
├── architecture_guide.md      # Core components, design, flows
├── sparse_attention_guide.md  # Sparse attention methods
├── layerwise_offload_memory_analysis.md  # Memory analysis
├── debugging_guide.md         # Debugging techniques
└── <new_topic>_guide.md       # New technical topic
```

### Step 3: Update CLAUDE.md Documentation Index

Add entry to the Documentation Index table:
```markdown
| Document | Purpose |
|----------|---------|
| [`docs/new_doc.md`](docs/new_doc.md) | Brief description |
```

### Step 4: Refactor if Needed

If CLAUDE.md grows too large (> 150 lines), refactor:
1. Identify technical details that can be moved
2. Create appropriate doc in docs/
3. Replace detailed content with reference link
4. Keep only operational essentials in CLAUDE.md

## Documentation Structure Template

For new technical docs:

```markdown
# Topic Guide

Brief overview of what this document covers.

## Section 1: Concepts
- Key concepts and terminology

## Section 2: Implementation
- Code locations
- Key methods/functions

## Section 3: Details
- Detailed explanations
- Code examples

## Section 4: Validation (if applicable)
- Theoretical analysis
- Empirical measurements
- Comparison table
```

## Memory Analysis Template

When documenting memory behavior:

```markdown
## Theoretical Calculation

| Component | Formula | Size |
|-----------|---------|------|
| Buffer X | `param1 × param2 × dtype_size` | X MB |

## Empirical Validation

| Metric | Theoretical | Actual | Error |
|--------|-------------|--------|-------|
| Peak memory | X GB | Y GB | Z% |

## Key Findings
1. Finding 1
2. Finding 2
```