# Story 12.14: Expand Competitor Comparison Documentation

**Status:** Complete
**Priority:** Medium
**Depends on:** None
**Effort:** Medium (2-3 days)

---

## Problem Statement

We have comprehensive competitive research, but it's not reaching evaluators:

1. **Buried in repo** - Excel file in `docs/audits/` that users browsing docs.fapilog.dev will never see
2. **Buried in navigation** - `user-guide/comparisons.md` is 2+ clicks deep, not in main nav
3. **Incomplete** - current comparison only covers 3 competitors with basic matrix
4. **Missing landing page** - no dedicated "Why Fapilog?" page (noted in `docs/milestones.md:138`)

**Key insight:** Most people evaluating fapilog will browse docs.fapilog.dev, not deep-dive the GitHub repo. The comparison must be prominent in the *built documentation*, not just exist in the repo.

### Current State

| Asset | Location | Problem |
|-------|----------|---------|
| Competitor research | `docs/audits/*.xlsx` | Only visible in repo, not built docs |
| Published comparison | `docs/user-guide/comparisons.md` | Buried 2 levels deep in nav |
| "Why Fapilog?" | README + docs index (brief) | No dedicated page, not in nav |

### Target Search Queries

- "python logging library comparison"
- "structlog vs loguru"
- "fapilog vs structlog"
- "best python logging library 2026"
- "async python logging"
- "python logging performance comparison"

---

## Goals

1. Surface competitive research as discoverable documentation
2. Create SEO-optimized "Why Fapilog?" landing page
3. Expand comparison matrix to cover all researched libraries
4. Add quantitative performance data
5. Help users make informed library choices

---

## Scope

### In Scope

- Create top-level `docs/comparisons.md` with expanded feature matrix (4 competitors)
- Create top-level `docs/why-fapilog.md` as dedicated landing page
- Add both to main navigation (prominent, not buried)
- Add performance comparison section with benchmark references
- Update README and docs index to link to new pages
- Redirect old `user-guide/comparisons.md` to new location
- Ensure all claims are accurate and verifiable

### Out of Scope

- Running new benchmarks (use existing data)
- Detailed migration guides from each competitor
- Video or interactive content
- Translations

---

## Acceptance Criteria

### AC1: Expanded Feature Comparison

- [ ] `docs/user-guide/comparisons.md` includes the 4 most relevant alternatives:
  - **structlog** - Main structured logging competitor
  - **loguru** - DX-focused competitor (21k GitHub stars)
  - **stdlib logging** - Baseline everyone knows
  - **OpenTelemetry** - For users considering full observability
- [ ] Feature categories cover: Core Architecture, Async/Backpressure, Structured Logging, Framework Integration, Security & Redaction, Performance
- [ ] Legend explains symbols: ✅ Full support, ⚠️ Partial/manual, ❌ Not available
- [ ] Excludes niche/inactive libraries (aiologger, loki-handler, python-json-logger)

### AC2: "Why Fapilog?" Landing Page

- [ ] `docs/why-fapilog.md` exists with SEO-optimized title
- [ ] Includes quick decision matrix: "Use fapilog if... / Use X if..."
- [ ] Highlights unique differentiators:
  - Async-first with backpressure policies
  - Built-in multi-stage redaction
  - FastAPI middleware out-of-box
  - Level-based sink routing
- [ ] Links to detailed comparison page
- [ ] Honest about trade-offs (maturity, community size)

### AC3: Performance Section

- [ ] Comparison page includes performance characteristics table
- [ ] Throughput, latency, memory, backpressure handling compared
- [ ] Links to `docs/user-guide/benchmarks.md` for methodology
- [ ] Avoids hard claims that could become outdated; uses ranges

### AC4: Architecture Comparison

- [ ] Section explaining architectural differences
- [ ] Table: Architecture type, concurrency model, queue type, I/O model
- [ ] Helps users understand why fapilog's design matters

### AC5: Prominent Placement in Built Docs

- [ ] `why-fapilog.md` is top-level in toctree (appears in sidebar nav on every page)
- [ ] `comparisons.md` is top-level in toctree (not buried in user-guide)
- [ ] Navigation order: Getting Started → Why Fapilog → Comparisons → Core Concepts
- [ ] `docs/index.md` "Why Fapilog?" section links to dedicated page
- [ ] Old `user-guide/comparisons.md` redirects to new top-level location
- [ ] README "Why fapilog?" section links to docs.fapilog.dev/why-fapilog/

### AC6: Evaluator Journey

- [ ] User landing on docs homepage sees "Why Fapilog?" in first scroll
- [ ] Comparison page reachable in 1 click from homepage
- [ ] Comparison page reachable from sidebar on any page
- [ ] No need to browse repo to find competitive positioning

### AC7: Accuracy Verification

- [ ] All competitor claims verified against current documentation
- [ ] Version numbers and stars updated (or stated as "as of date")
- [ ] No false negatives (claiming competitors lack features they have)
- [ ] No false positives (claiming fapilog has features it doesn't)

---

## Technical Design

### File Structure

```
docs/
├── index.md                          # UPDATE: Link to why-fapilog prominently
├── why-fapilog.md                    # NEW: Top-level landing page (in main nav)
├── comparisons.md                    # NEW: Top-level comparison (in main nav)
├── user-guide/
│   └── comparisons.md                # DEPRECATE: Redirect to top-level
└── audits/
    └── fapilog_competitor_comparison.xlsx  # Source data (keep)
```

**Key change:** Comparisons move from buried `user-guide/comparisons.md` to top-level `comparisons.md` in main navigation. This ensures evaluators find it without digging.

### Navigation Placement

The main toctree in `docs/index.md` should include these as top-level items:

```rst
:caption: Documentation

getting-started/index
why-fapilog           # NEW - appears right after getting-started
comparisons           # NEW - prominent for evaluators
core-concepts/index
user-guide/index
...
```

This puts "Why Fapilog?" and "Comparisons" in the primary navigation sidebar on ReadTheDocs, visible on every page.

### "Why Fapilog?" Page Structure

```markdown
# Why Fapilog?

{First paragraph with SEO keywords: async logging, structured logging, FastAPI, Python}

## Quick Decision Guide

| If you need... | Best choice |
|----------------|-------------|
| Async-first logging with backpressure | **fapilog** |
| Simplest possible API, sync is fine | loguru |
| Processor ecosystem, stdlib compatibility | structlog |
| Full observability (logs+traces+metrics) | OpenTelemetry |
| Zero dependencies | stdlib logging |

## What Makes Fapilog Different

### 1. True Async-First Design
Non-blocking by default. Your API latency doesn't suffer when sinks are slow.

### 2. Backpressure Policies
Choose what happens when the queue fills: drop, wait, or discard oldest.

### 3. Built-in Redaction
PII and secrets masked by default. No compliance surprises.

### 4. FastAPI Integration
One line: `lifespan = setup_logging(preset="fastapi")`

## Honest Trade-offs

| Consideration | Reality |
|---------------|---------|
| **Maturity** | New (2024) vs structlog (2013), loguru (2018) |
| **Community** | Growing vs established ecosystems |
| **Sync use cases** | If you don't need async, loguru is simpler |

## Learn More

- [Full feature comparison](comparisons.md) - fapilog vs structlog vs loguru vs stdlib vs OpenTelemetry
- [Architecture](architecture/index.md) - How the async pipeline works
- [Cookbook](cookbook/index.md) - Copy-paste solutions
```

### Expanded Comparison Page Structure

```markdown
# Python Logging Library Comparison

Comparing fapilog with the libraries Python developers most commonly consider.

## Quick Decision Matrix

| If you need... | Best choice |
|----------------|-------------|
| Async-first + backpressure | fapilog |
| Simplest possible API | loguru |
| Processor ecosystem + stdlib compat | structlog |
| Full observability (traces+metrics) | OpenTelemetry |
| Zero dependencies | stdlib logging |

## Feature Comparison

### Core Architecture & Async Support
{5-column table: fapilog, structlog, loguru, stdlib, OpenTelemetry}

### Structured Logging & Context
{Table}

### Security & Redaction
{Table - fapilog strength}

### Framework Integration
{Table - FastAPI/Django/Flask}

### Performance
{Throughput, latency, backpressure}

## When to Use Each

### fapilog
Best for: FastAPI/async services, compliance requirements, high-throughput

### structlog
Best for: Existing stdlib codebases, processor customization

### loguru
Best for: Scripts, prototypes, dev experience priority

### stdlib logging
Best for: Zero dependencies, maximum compatibility

### OpenTelemetry
Best for: Full observability stack, vendor-neutral telemetry

## Trade-offs

{Honest assessment of fapilog's limitations: maturity, community size}
```

---

## Tasks

### Phase 1: Create "Why Fapilog?" Page
- [ ] Create `docs/why-fapilog.md`
- [ ] Write quick decision guide
- [ ] Document unique differentiators
- [ ] Add honest trade-offs section
- [ ] Link to detailed comparison

### Phase 2: Expand Comparison Matrix
- [ ] Create new `docs/comparisons.md` (top-level, not in user-guide)
- [ ] Include 4 focused competitors: structlog, loguru, stdlib, OpenTelemetry
- [ ] Create sections for each feature category
- [ ] Add performance characteristics table
- [ ] Add architecture comparison table

### Phase 3: Verify Accuracy
- [ ] Cross-check structlog claims against structlog.org docs
- [ ] Cross-check loguru claims against loguru.readthedocs.io
- [ ] Cross-check OpenTelemetry claims against opentelemetry.io
- [ ] Cross-check stdlib claims against docs.python.org
- [ ] Update GitHub stars and version numbers (date the snapshot)

### Phase 4: Prominent Navigation Placement
- [ ] Create `docs/why-fapilog.md` at top level
- [ ] Create `docs/comparisons.md` at top level (not in user-guide)
- [ ] Update `docs/index.md` toctree to include both as top-level items
- [ ] Position after "Getting Started" in navigation order
- [ ] Add redirect from old `user-guide/comparisons.md` location
- [ ] Update `docs/index.md` "Why Fapilog?" section to link to dedicated page

### Phase 5: External Linking
- [ ] Update README "Why fapilog?" section with link to docs.fapilog.dev/why-fapilog/
- [ ] Update PyPI description to mention comparison page
- [ ] Add links from getting started guide
- [ ] Add "See also" links in cookbook entries

### Phase 6: Documentation Build
- [ ] Verify pages appear in sidebar navigation
- [ ] Verify navigation order is correct
- [ ] Verify redirect works from old location
- [ ] Check all internal links work
- [ ] Test on ReadTheDocs preview

---

## Source Data

All competitive analysis sourced from:
- `docs/audits/fapilog_competitor_analysis.md` (January 2026)

**Focused comparison set** (4 libraries users actually consider):

| Library | Why Include | Unique Strength | Gap vs fapilog |
|---------|-------------|-----------------|----------------|
| **structlog** | Main structured logging competitor | Processor ecosystem, 10+ years maturity | No async pipeline, no backpressure |
| **loguru** | What devs reach for first (21k stars) | Developer experience (10/10), beautiful defaults | No async, no redaction, sync I/O |
| **stdlib** | Baseline everyone knows | Zero dependencies, universal | No structure, no redaction, verbose |
| **OpenTelemetry** | Enterprise observability consideration | Logs+traces+metrics unified | Complexity, overhead, not logging-focused |

**Excluded** (too niche or inactive):
- aiologger: Inactive since 2022, stdout-only
- loki-handler: Single destination
- python-json-logger: Just a formatter, not a solution

---

## Tests

### Manual Verification

- [ ] All external links to competitor docs work
- [ ] Feature claims match competitor documentation
- [ ] Performance ranges are reasonable
- [ ] No broken internal links

### Documentation Build

- [ ] `make docs` succeeds
- [ ] New pages appear in navigation
- [ ] Tables render correctly

---

## Definition of Done

### Content Complete
- [ ] "Why Fapilog?" page written and linked
- [ ] Comparison page covers 4 key competitors (structlog, loguru, stdlib, OpenTelemetry)
- [ ] Performance section added
- [ ] Architecture comparison added

### Accuracy
- [ ] All competitor claims verified
- [ ] Version/metadata dated
- [ ] Trade-offs honestly stated

### SEO
- [ ] Primary keywords in H1 and first paragraphs
- [ ] Competitor names in headings for search
- [ ] Internal linking complete

---

## Risks

### Risk 1: Claims become outdated
- **Mitigation:** Date all version/star counts; use ranges not absolutes; link to competitor docs

### Risk 2: Appear biased/unfair to competitors
- **Mitigation:** Acknowledge competitor strengths; be honest about fapilog trade-offs

### Risk 3: Competitors release new features
- **Mitigation:** Focus on architectural differences (stable); avoid feature nitpicking

---

## Success Metrics

- Search traffic to comparison and why-fapilog pages
- Time on page (engagement with detailed content)
- Conversion: users who visit comparison → install fapilog

---

## Related Documents

- [Competitor Analysis](../audits/fapilog_competitor_analysis.md)
- [Current Comparison Page](../user-guide/comparisons.md)
- [Milestones - Why Fapilog page](../milestones.md#line-138)
- [Cookbook Series Overview](./12.0-series-overview.md)

---

## Code Review

**Date:** 2026-01-22
**Reviewer:** Claude
**Verdict:** OK to PR

### Summary

Reviewed new why-fapilog.md landing page and expanded comparisons.md covering structlog, loguru, stdlib, and OpenTelemetry with feature matrices, architecture diagrams, and migration examples.

### AC Verification

| Criterion | Evidence |
|-----------|----------|
| AC1: Expanded Feature Comparison | `comparisons.md:1-257` - 4 competitors, 6 feature tables, legend |
| AC2: "Why Fapilog?" Landing Page | `why-fapilog.md:1-122` - Decision guide, differentiators, trade-offs |
| AC3: Performance Section | `comparisons.md:124-131` - Performance table with benchmarks link |
| AC4: Architecture Comparison | `comparisons.md:76-83,134-182` - Architecture table and diagrams |
| AC5: Prominent Placement | `index.md:60-61` - Top-level toctree, redirect in place |
| AC6: Evaluator Journey | `index.md:17` - Links in first scroll, sidebar access |
| AC7: Accuracy Verification | `comparisons.md:10` - Dated January 2026, claims verified |

### Quality Gates

- [x] Documentation builds without warnings (`sphinx-build -W`)
- [x] Navigation order correct
- [x] All internal links work
- [x] Redirect in place for old location

---

## Change Log

| Date       | Change               | Author |
| ---------- | -------------------- | ------ |
| 2026-01-22 | Initial story creation | Claude |
| 2026-01-22 | Focused to 4 competitors; fixed top-level placement; corrected internal links | Claude |
| 2026-01-22 | Implementation complete, code review passed | Claude |
