# Story 12.0: Epic 12 Overview - Cookbook (SEO-Driven Documentation)

## Context / Background

The cookbook is a collection of short, runnable guides targeting high-frequency "how do I..." queries. Each page is optimized for SEO to drive traffic to the fapilog repository and convert searchers into users.

**Primary goals:**

1. **Drive traffic** - Target exact search phrases developers use
2. **Demonstrate differentiation** - Show where fapilog solves problems better than alternatives
3. **Convert to users** - Short, runnable examples that "just work"

**SEO principles:**

- Put the search phrase in H1 and first paragraph
- Keep pages short: problem → snippet → gotchas → deeper links
- Link from PyPI description, README, and Getting Started

## Story Status

### P0: "This will bring users" (write these first)

| Story | Title | Status |
|-------|-------|--------|
| 12.1 | FastAPI request_id logging (correlation ID middleware, concurrency-safe) | Ready |
| 12.2 | FastAPI JSON logging to stdout (Uvicorn access logs included) | Ready |
| 12.3 | Non-blocking logging in FastAPI (protect latency under slow sinks) | Ready |

### P1: High-demand, high-conversion

| Story | Title | Status |
|-------|-------|--------|
| 12.4 | One FastAPI logging config for dev + prod (Uvicorn/Gunicorn) | Ready |
| 12.5 | Redacting secrets and PII in FastAPI logs (Authorization, tokens, fields) | Ready |
| 12.6 | Logging request/response bodies without hanging (safe patterns) | Ready |

### P2: Round out the story

| Story | Title | Status |
|-------|-------|--------|
| 12.7 | Skipping health/metrics endpoints (noise reduction) | Ready |
| 12.8 | Log sampling and rate limiting for FastAPI | Ready |
| 12.9 | Graceful shutdown & flushing logs (don't lose logs on deploy) | Ready |
| 12.10 | Exception logging in FastAPI with request_id + structured context | Ready |

### P3: Framework & Positioning Expansion

| Story | Title | Status |
|-------|-------|--------|
| 12.13 | Django Structured JSON Logging with Correlation IDs | Ready |
| 12.14 | Expand Competitor Comparison Documentation | Ready |

### Infrastructure

| Story | Title | Status |
|-------|-------|--------|
| 12.12 | Configure Custom Domain for RTD (docs.fapilog.dev) | ✅ Complete |
| 12.11 | Sitemap Generation for RTD (Stable/Canonical) and GH Pages (Latest/Edge) | Ready |

**Note:** 12.12 should be completed before 12.11 so canonical URLs use `docs.fapilog.dev`.

## Scope (In / Out)

### In Scope

- Create 10 cookbook documentation pages targeting specific SEO keywords
- Each page includes: problem statement, minimal working code, gotchas, deeper links
- Add cookbook section to docs navigation
- Link cookbook from PyPI description, README, Getting Started

### Out of Scope

- New library features (use existing fapilog capabilities)
- Video tutorials or interactive demos
- Translations to other languages
- Analytics/tracking implementation

## Acceptance Criteria

### AC1: Cookbook Section Created

**Description:** Cookbook directory exists with index and navigation integration.

**Validation:**
- `docs/cookbook/` directory exists
- `docs/cookbook/index.md` lists all cookbook pages
- Main docs navigation includes cookbook section

### AC2: SEO Optimization

**Description:** Each page follows SEO best practices.

**Validation:**
- H1 contains target search phrase
- First paragraph contains target keywords
- Page is under 1000 words (scannable)
- Code examples are copy-pasteable

### AC3: Cross-Linking

**Description:** Cookbook is discoverable from key entry points.

**Validation:**
- README.md links to cookbook
- PyPI description mentions cookbook
- Getting Started page references relevant cookbook entries

## Implementation Notes

### File Structure

```
docs/
├── why-fapilog.md                        # 12.14 - TOP-LEVEL in nav
├── comparisons.md                        # 12.14 - TOP-LEVEL in nav
├── cookbook/
│   ├── index.md                          # Cookbook landing page
│   ├── fastapi-request-id-logging.md     # 12.1
│   ├── fastapi-json-logging.md           # 12.2
│   ├── non-blocking-async-logging.md     # 12.3
│   ├── dev-prod-logging-config.md        # 12.4
│   ├── redacting-secrets-pii.md          # 12.5
│   ├── safe-request-response-logging.md  # 12.6
│   ├── skip-noisy-endpoints.md           # 12.7
│   ├── log-sampling-rate-limiting.md     # 12.8
│   ├── graceful-shutdown-flush.md        # 12.9
│   ├── exception-logging-request-context.md  # 12.10
│   └── django-structured-logging.md      # 12.13
└── user-guide/
    └── comparisons.md                    # REDIRECT to top-level
```

### Page Template

```markdown
# {SEO Title}

{First paragraph with target keywords - what problem this solves}

## The Problem

{Concrete description of the pain point}

## The Solution

```python
# Minimal working example
```

## Common Gotchas

{What people get wrong and how to avoid it}

## Going Deeper

- [Link to relevant docs section]
- [Link to related cookbook page]
```

## Tasks

### Phase 1: Infrastructure

- [ ] Create `docs/cookbook/` directory
- [ ] Create `docs/cookbook/index.md` landing page
- [ ] Add cookbook to docs navigation (conf.py/toctree)
- [ ] Update README with cookbook section

### Phase 2: P0 Pages (12.1-12.3)

- [ ] Story 12.1: FastAPI request_id logging
- [ ] Story 12.2: JSON logs to stdout
- [ ] Story 12.3: Non-blocking async logging

### Phase 3: P1 Pages (12.4-12.6)

- [ ] Story 12.4: Dev/prod logging config
- [ ] Story 12.5: Redacting secrets/PII
- [ ] Story 12.6: Safe body logging

### Phase 4: P2 Pages (12.7-12.10)

- [ ] Story 12.7: Skip noisy endpoints
- [ ] Story 12.8: Sampling/rate limiting
- [ ] Story 12.9: Graceful shutdown
- [ ] Story 12.10: Exception logging with context

### Phase 5: Cross-Linking

- [ ] Update PyPI description
- [ ] Update Getting Started docs
- [ ] Internal cross-links between cookbook pages

## Tests

- Manual review of each page for SEO checklist
- Link validation (no broken links)
- Code examples tested for correctness

## Definition of Done

### Content Complete

- [ ] All 10 cookbook pages written
- [ ] Each page follows template structure
- [ ] Code examples are tested and working

### SEO Optimized

- [ ] Target keywords in H1 and first paragraph
- [ ] Pages are scannable (short paragraphs, headers)
- [ ] Meta descriptions set (if supported)

### Integrated

- [ ] Cookbook in main navigation
- [ ] README links to cookbook
- [ ] Getting Started references cookbook

## Risks / Rollback

### Risks

1. **Risk:** Code examples become outdated with API changes
   - **Mitigation:** Add cookbook examples to CI test suite

2. **Risk:** SEO takes time to show results
   - **Mitigation:** Monitor Search Console, iterate on titles

### Rollback Plan

Documentation-only changes. Rollback by reverting commits.

## Related Stories

- **Related:** 10.3 One-Liner FastAPI Integration (provides setup_logging)
- **Related:** 10.2 Pretty Console Output (JSON formatting)
- **Related:** 5.3 Sampling and Rate Limiting Plugins

---

## Change Log

| Date | Change | Author |
|------|--------|--------|
| 2026-01-21 | Initial draft | Claude |
