Auto Doc Updater

Keep documentation accurate, current, and in sync with the actual codebase.

Core Principle

Documentation drift is a bug. Treat outdated docs with the same severity as a broken test. Every meaningful code change should trigger a documentation review.

When to Update Docs (Triggers)

README Maintenance

Standard README Structure

# Project Name

One-line description.

## Features
- Feature 1
- Feature 2

## Quick Start
\`\`\`bash
git clone ...
pnpm install
pnpm dev
\`\`\`

## Prerequisites
- Node.js 20+
- PostgreSQL 16+

## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `DATABASE_URL` | Yes | PostgreSQL connection string |

## Project Structure
\`\`\`
src/
├── ...
\`\`\`

## Scripts
| Command | Description |
|---------|-------------|
| `pnpm dev` | Start dev server |
| `pnpm test` | Run tests |

## Contributing
See CONTRIBUTING.md

## License
MIT

README Audit Checklist

• [ ] Quick Start commands actually work on a fresh clone
• [ ] All required env vars are listed in .env.example
• [ ] Dependency versions in README match package.json/Cargo.toml/pyproject.toml
• [ ] Screenshots/GIFs are current (not showing old UI)
• [ ] Links are not broken (internal anchors, external URLs)
• [ ] Badges (build status, version, license) are accurate

CHANGELOG Maintenance

Keep a Changelog Format

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]
### Added
- New `/api/export` endpoint for CSV export

### Changed
- Improved query performance for dashboard load

### Fixed
- Fixed timezone bug in date filters

## [1.3.0] - 2026-06-15
### Added
- Multi-tenant workspace support
- Passkey authentication

### Deprecated
- `/api/v1/users` — use `/api/v2/users` instead, removal in v2.0.0

### Security
- Patched RLS policy gap in `projects` table

Generating Changelog from Conventional Commits

# If using conventional commits (feat:, fix:, chore:, etc.)
npx conventional-changelog -p angular -i CHANGELOG.md -s

# Or use git-cliff (Rust-based, fast)
cargo install git-cliff
git-cliff --output CHANGELOG.md

# cliff.toml — git-cliff config
[git]
conventional_commits = true
filter_unconventional = false

[changelog]
header = "# Changelog\n\n"
body = """
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {{ commit.message | upper_first }}
{% endfor %}
{% endfor %}\n
"""

API Documentation

OpenAPI/Swagger Sync (FastAPI auto-generates)

# FastAPI generates OpenAPI spec automatically from type hints
# Just ensure docstrings and response_model are accurate

@router.post(
    "/posts",
    response_model=PostResponse,
    status_code=201,
    summary="Create a new post",
    description="Creates a post owned by the authenticated user. Requires `member` role or higher.",
    responses={
        401: {"description": "Not authenticated"},
        403: {"description": "Insufficient permissions"},
        422: {"description": "Validation error"},
    },
)
async def create_post(data: PostCreate, user: User = Depends(get_current_user)):
    ...

# Auto-exposed at /docs (Swagger UI) and /redoc

TSDoc for TypeScript APIs

/**
 * Creates a new post for the authenticated user.
 *
 * @param data - Post creation payload
 * @param data.title - Post title (1-200 chars)
 * @param data.content - Optional post body
 * @returns The created post with generated ID
 * @throws {ValidationError} If title is empty or exceeds 200 chars
 * @throws {UnauthorizedError} If user is not authenticated
 *
 * @example
 * ```ts
 * const post = await createPost({ title: "Hello", content: "World" })
 * ```
 */
export async function createPost(data: CreatePostInput): Promise<Post> {
  // ...
}

# Generate docs site from TSDoc
npx typedoc --out docs src/index.ts

Architecture Decision Records (ADRs)

# docs/adr/0003-use-drizzle-over-prisma.md

# ADR 0003: Use Drizzle ORM over Prisma

## Status
Accepted

## Date
2026-06-10

## Context
We need a type-safe ORM for PostgreSQL. Prisma requires a separate query engine binary
and has slower cold starts on serverless. Drizzle generates SQL at build time with no
runtime engine.

## Decision
Use Drizzle ORM for all database access.

## Consequences
### Positive
- Faster cold starts on Vercel serverless functions
- SQL-like query builder is more transparent
- No binary/engine dependency

### Negative
- Smaller ecosystem than Prisma
- Migration tooling (drizzle-kit) is less mature
- Team needs to learn new query syntax

## Alternatives Considered
- Prisma: rejected due to cold start overhead
- Raw SQL with `pg`: rejected — loses type safety

Doc Sync Automation Script

// scripts/check-docs-sync.ts
import fs from "fs"
import path from "path"

function checkEnvVarsSynced() {
  const envExample = fs.readFileSync(".env.example", "utf-8")
  const envVarsInExample = new Set(
    envExample.match(/^([A-Z_]+)=/gm)?.map(l => l.replace("=", "")) ?? []
  )

  // Scan source for process.env.X usage
  const srcFiles = getAllFiles("src", [".ts", ".tsx"])
  const envVarsInCode = new Set<string>()

  for (const file of srcFiles) {
    const content = fs.readFileSync(file, "utf-8")
    const matches = content.matchAll(/process\.env\.([A-Z_]+)/g)
    for (const match of matches) envVarsInCode.add(match[1])
  }

  const missing = [...envVarsInCode].filter(v => !envVarsInExample.has(v))
  if (missing.length > 0) {
    console.error("❌ Missing from .env.example:", missing)
    process.exit(1)
  }
  console.log("✅ .env.example is in sync")
}

checkEnvVarsSynced()

# Run in CI to catch doc drift
- name: Check docs sync
  run: npx tsx scripts/check-docs-sync.ts

Doc Review Checklist (Before Merging)

• [ ] README reflects any new setup steps
• [ ] .env.example has all new environment variables
• [ ] CHANGELOG has an entry under [Unreleased]
• [ ] API docs (OpenAPI/TSDoc) cover new/changed endpoints
• [ ] Breaking changes have a migration note
• [ ] Code comments explain why, not what (the code already shows what)
• [ ] Outdated screenshots/diagrams flagged for update
• [ ] No dead links introduced

Key Rules

1. Doc updates are part of the PR, not a follow-up task — same commit/PR as the code change
2. CHANGELOG `[Unreleased]` section updated with every notable change
3. `.env.example` must always match actual required env vars — verify in CI
4. ADRs for significant technical decisions — capture the "why," not just the "what"
5. Auto-generate API docs from code (OpenAPI, TSDoc) — avoid hand-maintained duplicates
6. Breaking changes need a migration guide, not just a changelog line
7. Quick Start in README must work on a clean checkout — test it periodically
8. Deprecations get a removal timeline — never silently remove without notice
9. Link-check docs in CI — broken links are a doc bug
10. Architecture diagrams updated when system boundaries change — not just code comments