Documentation Reviewer

Documentation Reviewer

Overview

Ensure documentation stays synchronized with code changes. Analyze git diffs, identify impacted documentation, and update MkDocs Material docs with proper formatting.

Workflow

1. Analyze Changes → 2. Map to Docs → 3. Identify Gaps → 4. Update Docs → 5. Verify

Step 1: Analyze Changes

Run the change analysis script or manually check:

# Using script (from project root)
python3 ~/.claude/skills/documentation-reviewer/scripts/analyze_changes.py

# Manual check
git diff --name-only HEAD~1  # or specify commit range
git diff --stat HEAD~1

Step 2: Map Changes to Documentation

See references/change-mapping.md for complete mapping rules.

Step 3: Identify Documentation Gaps

Check for missing documentation:

1. New exports - Public functions/classes need documentation
2. Changed behavior - Updated logic needs updated docs
3. New config options - Environment variables, settings
4. Breaking changes - Migration guides required
5. New dependencies - Installation instructions

Step 4: Update Documentation

Use MkDocs Material syntax from references/mkdocs-material-syntax.md:

• Admonitions for warnings/tips
• Code blocks with titles and line numbers
• Tabbed content for multi-platform instructions
• Tables for structured data
• Mermaid diagrams for architecture

Step 5: Verify

# Serve docs locally
mkdocs serve

# Check for broken links and build
mkdocs build --strict

Quick Reference

Must-Document Changes

• New API endpoints
• New CLI commands/invoke tasks
• Configuration changes
• Breaking changes
• New features
• Security-related changes

Documentation Checklist

• Updated relevant docs page(s)
• Added to mkdocs.yml nav if new page
• Code examples are accurate and tested
• Links are valid
• Consistent with existing style

Resources

• references/mkdocs-material-syntax.md - Formatting patterns and examples
• references/change-mapping.md - Code-to-docs mapping rules
• references/documentation-standards.md - Writing style and structure
• scripts/analyze_changes.py - Git diff analysis tool