# Story 10.9: DX Documentation and Migration Guide

## Status: Planned

## Priority: High

## Estimated Effort: Medium (2-3 days)

## Dependencies

- **Depends on:** Stories 10.1-10.8 (All DX features) - Documents all new features

## Epic / Series

Part of Epic 10: Developer Experience and Ergonomics / Series 10.x

---

## Context / Background

DX improvements (Stories 10.1-10.8) introduce significant ergonomic improvements:
- **Presets** (10.1) - Quick configuration for common use cases
- **Pretty console output** (10.2) - Human-readable development logs
- **One-liner FastAPI integration** (10.3) - `setup_logging()` for FastAPI apps
- **Human-readable config strings** (10.4) - "10 MB", "daily" instead of bytes/seconds
- **Simplified file rotation API** (10.5) - Easier file sink configuration
- **Enhanced defaults** (10.6) - Smart TTY/CI detection and sink fallback
- **Fluent builder API** (10.7) - Method chaining for configuration
- **Environment auto-detection** (10.8) - Automatic Docker/K8s/Lambda configuration

**This story ensures all these features are properly documented** with:
- Clear examples and quick start guides
- Migration paths from other logging libraries
- Updated API reference
- Working examples in CI

## Scope (In / Out)

### In Scope

- **Update comparison page** (`docs/user-guide/comparisons.md`) with new DX features
- **Update quick start guide** (`docs/getting-started/quickstart.md`) with presets and one-liner FastAPI
- **Create migration guides** (`docs/guides/migration-*.md`) for:
  - stdlib logging → fapilog
  - loguru → fapilog
  - structlog → fapilog
  - Older fapilog → new DX features
- **Update API reference** (`docs/api-reference/`) for:
  - Presets (`get_logger(preset=...)`)
  - Builder API (`LoggerBuilder`, `AsyncLoggerBuilder`)
  - FastAPI integration (`setup_logging()`, `get_request_logger()`)
  - Environment auto-detection (`auto_detect`, `environment` parameters)
  - Human-readable strings (Story 10.4)
- **Update examples** (`examples/`) with new features:
  - Presets examples (already exist, verify completeness)
  - FastAPI one-liner examples (already exist, verify completeness)
  - Builder API examples (NEW)
  - Environment auto-detection examples (NEW)
- **Update FAQ** (`docs/faq.md`) with common questions about new features

### Out of Scope

- Video tutorials or marketing content beyond documentation
- External blog posts or community tutorials
- Documentation for features not yet implemented (wait for Stories 10.1-10.8 completion)

## Acceptance Criteria

### AC1: Updated Comparison Page

**Comparison page (`docs/user-guide/comparisons.md`) includes new DX features:**

- Presets comparison (fapilog presets vs manual configuration in others)
- One-liner FastAPI setup comparison
- Builder API mention (if applicable)
- Environment auto-detection mention
- Human-readable config strings mention

**Example additions:**
```markdown
| Feature | fapilog | loguru | structlog |
|---------|---------|--------|-----------|
| Presets | ✅ dev, production, fastapi, minimal | ❌ | ❌ |
| One-liner FastAPI | ✅ `setup_logging()` | ❌ | ❌ |
| Builder API | ✅ `LoggerBuilder()` | ❌ | ❌ |
| Auto-detection | ✅ Docker/K8s/Lambda | ❌ | ❌ |
```

### AC2: Updated Quick Start Guide

**Quick start guide (`docs/getting-started/quickstart.md`) shows:**

- Presets usage: `get_logger(preset="production")`
- One-liner FastAPI: `app = FastAPI(lifespan=setup_logging())`
- Human-readable strings: `max_bytes="10 MB"`, `interval="daily"`
- Environment auto-detection: `get_logger()` automatically detects environment

**Structure:**
1. Zero-config (existing)
2. With presets (NEW)
3. FastAPI one-liner (NEW)
4. Environment auto-detection (NEW)

### AC3: Migration Guides

**Create migration guides in `docs/guides/`:**

1. **`migration-stdlib.md`** - stdlib logging → fapilog
   - Basic logging translation
   - Handler → Sink mapping
   - Formatter → Enricher mapping
   - Context propagation differences

2. **`migration-loguru.md`** - loguru → fapilog
   - API surface comparison
   - Context binding differences
   - Sink configuration differences
   - Async considerations

3. **`migration-structlog.md`** - structlog → fapilog
   - Processor → Enricher mapping
   - Context binding differences
   - Structured output comparison
   - Async pipeline differences

4. **`migration-fapilog-v2-to-v3.md`** - Older fapilog → new DX features
   - Presets usage
   - FastAPI integration changes
   - New configuration options
   - Backward compatibility notes

**Each guide includes:**
- Side-by-side code examples
- Feature mapping table
- Common pitfalls and solutions
- Performance considerations

### AC4: Updated API Reference

**API reference (`docs/api-reference/`) updated for:**

1. **`top-level-functions.md`**:
   - `preset` parameter documented with all presets
   - `format` parameter documented ("json", "pretty", "auto")
   - `auto_detect` and `environment` parameters (Story 10.8)
   - Builder API functions (Story 10.7)

2. **`configuration.md`**:
   - Human-readable strings (Story 10.4): "10 MB", "daily"
   - Presets section
   - Environment auto-detection section

3. **NEW: `builder-api.md`** (if Story 10.7 implemented):
   - `LoggerBuilder` class
   - `AsyncLoggerBuilder` class
   - All builder methods
   - Examples and comparison with Settings

4. **NEW: `fastapi-integration.md`** (or update existing):
   - `setup_logging()` function
   - `get_request_logger()` dependency
   - Middleware configuration
   - Examples

### AC5: Updated Examples

**Examples (`examples/`) updated and tested:**

1. **Presets examples** (`examples/presets/`):
   - ✅ Already exist: `dev_preset.py`, `production_preset.py`, `fastapi_preset.py`, `minimal_preset.py`
   - Verify all presets are demonstrated
   - Add README explaining when to use each

2. **FastAPI examples** (`examples/fastapi_one_liner/`):
   - ✅ Already exist: `main.py`, `with_config.py`, `with_lifespan.py`
   - Verify one-liner setup is clear
   - Add examples for middleware customization

3. **NEW: Builder API examples** (`examples/builder_api/`):
   - `basic_builder.py` - Simple builder usage
   - `preset_with_overrides.py` - Preset + builder overrides
   - `multiple_sinks.py` - Builder with multiple sinks
   - `async_builder.py` - AsyncLoggerBuilder usage

4. **NEW: Environment auto-detection examples** (`examples/environment_detection/`):
   - `docker_example.py` - Docker detection
   - `kubernetes_example.py` - Kubernetes detection
   - `lambda_example.py` - Lambda detection
   - `local_vs_production.py` - Local vs production behavior

5. **All examples tested in CI:**
   - Examples run without errors
   - Output format validated
   - Integration tests pass

### AC6: Updated FAQ

**FAQ (`docs/faq.md`) updated with:**

- **Presets questions:**
  - "Which preset should I use?"
  - "Can I override preset settings?"
  - "How do presets compare to manual configuration?"

- **FastAPI integration questions:**
  - "How do I use fapilog with FastAPI?"
  - "Do I need to manually add middleware?"
  - "How do I customize FastAPI logging?"

- **Builder API questions:**
  - "When should I use Builder vs Settings?"
  - "Can I use Builder with presets?"

- **Environment auto-detection questions:**
  - "How does environment detection work?"
  - "Can I disable auto-detection?"
  - "What if detection is wrong?"

- **Human-readable strings questions:**
  - "What string formats are supported?"
  - "Can I use strings in environment variables?"

## Implementation Notes

### Documentation Structure

**Existing structure to leverage:**
- `docs/user-guide/comparisons.md` - Update with new features
- `docs/getting-started/quickstart.md` - Update with presets and FastAPI
- `docs/api-reference/` - Update existing, add new pages
- `docs/guides/` - Create migration guides here
- `docs/faq.md` - Update with new questions
- `examples/` - Update existing, add new examples

### Documentation Standards

**Follow existing patterns:**
- Use code examples with syntax highlighting
- Include "Before/After" comparisons for migrations
- Link to related documentation
- Use consistent formatting (see `docs/style-guide.md`)

### Example Validation

**Examples must:**
- Run without errors in CI
- Produce expected output format
- Be tested via existing CI examples tests
- Include README files explaining purpose

### Migration Guide Format

**Each migration guide should include:**
1. **Overview** - Why migrate, key differences
2. **Quick Reference** - Feature mapping table
3. **Step-by-Step Migration** - Code examples
4. **Common Patterns** - Real-world scenarios
5. **Troubleshooting** - Common issues and solutions
6. **Performance Notes** - Performance considerations

### API Reference Updates

**When updating API reference:**
- Maintain existing format and structure
- Add new parameters to function signatures
- Include examples for new features
- Cross-reference related documentation
- Update type hints if changed

## Tasks

### Phase 1: Comparison and Quick Start Updates

- [ ] Update `docs/user-guide/comparisons.md`:
  - [ ] Add presets row to comparison table
  - [ ] Add FastAPI one-liner row
  - [ ] Add builder API row (if implemented)
  - [ ] Add environment auto-detection row
  - [ ] Add human-readable strings row

- [ ] Update `docs/getting-started/quickstart.md`:
  - [ ] Add "Using Presets" section with examples
  - [ ] Add "FastAPI One-Liner" section
  - [ ] Add "Environment Auto-Detection" section
  - [ ] Update "Environment Variables" section with human-readable strings
  - [ ] Add links to migration guides

### Phase 2: Migration Guides

- [ ] Create `docs/guides/migration-stdlib.md`:
  - [ ] Overview and motivation
  - [ ] Feature mapping table
  - [ ] Basic logging translation examples
  - [ ] Handler → Sink mapping
  - [ ] Formatter → Enricher mapping
  - [ ] Context propagation differences
  - [ ] Common patterns and pitfalls

- [ ] Create `docs/guides/migration-loguru.md`:
  - [ ] Overview and motivation
  - [ ] API surface comparison
  - [ ] Context binding differences
  - [ ] Sink configuration differences
  - [ ] Async considerations
  - [ ] Common patterns and pitfalls

- [ ] Create `docs/guides/migration-structlog.md`:
  - [ ] Overview and motivation
  - [ ] Processor → Enricher mapping
  - [ ] Context binding differences
  - [ ] Structured output comparison
  - [ ] Async pipeline differences
  - [ ] Common patterns and pitfalls

- [ ] Create `docs/guides/migration-fapilog-v2-to-v3.md`:
  - [ ] Overview of DX improvements
  - [ ] Presets usage guide
  - [ ] FastAPI integration changes
  - [ ] New configuration options
  - [ ] Backward compatibility notes
  - [ ] Migration checklist

### Phase 3: API Reference Updates

- [ ] Update `docs/api-reference/top-level-functions.md`:
  - [ ] Document `preset` parameter with all presets
  - [ ] Document `format` parameter ("json", "pretty", "auto")
  - [ ] Document `auto_detect` parameter (Story 10.8)
  - [ ] Document `environment` parameter (Story 10.8)
  - [ ] Add examples for each new parameter

- [ ] Update `docs/api-reference/configuration.md`:
  - [ ] Add "Presets" section
  - [ ] Add "Human-Readable Strings" section (Story 10.4)
  - [ ] Add "Environment Auto-Detection" section (Story 10.8)
  - [ ] Update examples with new features

- [ ] Create `docs/api-reference/builder-api.md` (if Story 10.7 implemented):
  - [ ] `LoggerBuilder` class documentation
  - [ ] `AsyncLoggerBuilder` class documentation
  - [ ] All builder methods with signatures
  - [ ] Examples and comparison with Settings
  - [ ] When to use Builder vs Settings

- [ ] Create or update `docs/api-reference/fastapi-integration.md`:
  - [ ] `setup_logging()` function documentation
  - [ ] `get_request_logger()` dependency documentation
  - [ ] Middleware configuration
  - [ ] Examples for common scenarios

### Phase 4: Examples Updates

- [ ] Verify and update `examples/presets/`:
  - [ ] Verify all presets are demonstrated
  - [ ] Add README explaining when to use each preset
  - [ ] Add examples for preset overrides

- [ ] Verify and update `examples/fastapi_one_liner/`:
  - [ ] Verify one-liner setup is clear
  - [ ] Add examples for middleware customization
  - [ ] Add examples for different presets

- [ ] Create `examples/builder_api/` (if Story 10.7 implemented):
  - [ ] `basic_builder.py` - Simple builder usage
  - [ ] `preset_with_overrides.py` - Preset + builder overrides
  - [ ] `multiple_sinks.py` - Builder with multiple sinks
  - [ ] `async_builder.py` - AsyncLoggerBuilder usage
  - [ ] `README.md` - Explanation and usage

- [ ] Create `examples/environment_detection/` (if Story 10.8 implemented):
  - [ ] `docker_example.py` - Docker detection
  - [ ] `kubernetes_example.py` - Kubernetes detection
  - [ ] `lambda_example.py` - Lambda detection
  - [ ] `local_vs_production.py` - Local vs production behavior
  - [ ] `README.md` - Explanation and usage

- [ ] Ensure all examples are tested in CI:
  - [ ] Examples run without errors
  - [ ] Output format validated
  - [ ] Integration tests pass

### Phase 5: FAQ Updates

- [ ] Update `docs/faq.md`:
  - [ ] Add "Presets" section with common questions
  - [ ] Add "FastAPI Integration" section
  - [ ] Add "Builder API" section (if implemented)
  - [ ] Add "Environment Auto-Detection" section (if implemented)
  - [ ] Add "Human-Readable Strings" section
  - [ ] Update existing questions with new features

### Phase 6: Documentation Validation

- [ ] Run link validation (`docs/validate_links.py`)
- [ ] Verify all examples run in CI
- [ ] Review documentation for clarity and completeness
- [ ] Check cross-references between docs
- [ ] Verify migration guides are accurate

## Tests

### Documentation Tests

- [ ] Link validation passes (`docs/validate_links.py`)
- [ ] Documentation builds successfully (if using Sphinx/MkDocs)
- [ ] All code examples are syntax-validated
- [ ] Cross-references are valid

### Example Tests

- [ ] All examples in `examples/` run without errors
- [ ] Examples produce expected output format
- [ ] Integration tests pass for new examples
- [ ] Examples are tested in CI (if CI examples tests exist)

### Content Validation

- [ ] Migration guides have accurate code translations
- [ ] API reference matches implementation
- [ ] Examples match documented behavior
- [ ] FAQ answers are accurate and helpful

## Definition of Done

Story is complete when ALL of the following are true:

### Code Complete
- [ ] All acceptance criteria met and verified
- [ ] All tasks completed
- [ ] Code follows project style guide
- [ ] No linting errors or warnings
- [ ] Type checking passes (mypy strict)

### Quality Assurance
- [ ] Unit tests: >90% coverage of new code
- [ ] Integration tests: all scenarios passing
- [ ] Regression tests: no existing functionality broken
- [ ] Performance tests: no regression vs baseline
- [ ] Manual testing completed (if applicable)

### Documentation
- [ ] User-facing docs updated
- [ ] API reference updated (if applicable)
- [ ] Code examples added/updated
- [ ] CHANGELOG.md updated
- [ ] Inline code documentation complete

### Review & Release
- [ ] Code review approved
- [ ] Documentation reviewed for clarity
- [ ] CI/CD pipeline passing
- [ ] Ready for merge to main branch

### Backwards Compatibility
- [ ] No breaking changes OR breaking changes documented with migration guide
- [ ] Existing tests still pass
- [ ] Deprecation warnings added (if applicable)

---

## Risks / Rollback / Monitoring

### Risks

- **Risk:** Docs drift from implementation
  - **Mitigation:** Regular reviews, link validation in CI
  - **Mitigation:** Examples tested in CI to catch drift
  - **Mitigation:** Code review includes documentation review

- **Risk:** Migration guides become outdated
  - **Mitigation:** Version migration guides, regular updates
  - **Mitigation:** Link to specific fapilog versions in guides
  - **Mitigation:** Include "Last updated" dates

- **Risk:** Examples don't work in all environments
  - **Mitigation:** Test examples in CI across Python versions
  - **Mitigation:** Include environment requirements in READMEs
  - **Mitigation:** Provide Docker-based examples where possible

- **Risk:** Documentation is too verbose or too terse
  - **Mitigation:** Follow existing documentation style guide
  - **Mitigation:** Peer review for clarity
  - **Mitigation:** Include "Quick Reference" sections

### Rollback Plan

- Keep docs changes isolated
- Revert if APIs change
- Documentation can be updated independently

### Success Metrics / Monitoring

- Track docs issues and usage feedback
- Monitor migration guide usage
- User feedback on documentation clarity

---

## Related Documents

- [Story 10.0: Series Overview](./10.0-series-overview.md)
- [Story 10.1: Configuration Presets](./10.1.configuration-presets.md) - ✅ Complete
- [Story 10.2: Pretty Console Output](./10.2.pretty-console-output.md) - ✅ Complete
- [Story 10.3: One-Liner FastAPI Integration](./10.3.one-liner-fastapi-integration.md) - ✅ Complete
- [Story 10.4: Human-Readable Config Strings](./10.4.human-readable-config-strings.md) - 📝 Planned
- [Story 10.5: Simplified File Rotation API](./10.5.simplified-file-rotation-api.md) - 📝 Planned
- [Story 10.6: Enhanced Default Behaviors](./10.6.enhanced-default-behaviors.md) - 📝 Planned
- [Story 10.7: Fluent Builder API](./10.7.fluent-builder-api.md) - 📝 Planned
- [Story 10.8: Smart Environment Auto-Detection](./10.8.smart-environment-auto-detection.md) - 📝 Planned
- [Epic 10: Developer Experience](../prd/epic-10-DX-Experience.md)

## Documentation Dependencies

**This story depends on Stories 10.1-10.8 being implemented first:**
- Story 10.1 (Presets) - ✅ Complete, can document now
- Story 10.2 (Pretty Output) - ✅ Complete, can document now
- Story 10.3 (FastAPI) - ✅ Complete, can document now
- Stories 10.4-10.8 - 📝 Planned, document after implementation

**Note**: Documentation can be written incrementally as features are completed, but this story tracks the complete documentation effort.

---

## Change Log

| Date       | Change                                                    | Author |
| ---------- | --------------------------------------------------------- | ------ |
| 2025-01-10 | Migrated to new format                                    | System |
| 2025-01-11 | Expanded with detailed acceptance criteria, tasks, and implementation notes | Review |
