Docs Codebase

Technical Documentation

Execution-ready patterns for clear, maintainable technical documentation.

Modern best practices (January 2026): docs-as-code, ownership + review cadence, documentation QA gates (links/style/spelling), AI-assisted drafting + review, OpenAPI 3.2.0 where streaming schemas matter, and GEO (Generative Engine Optimization) for AI search.

Quick Reference

Workflow

1. Identify the documentation type and audience.
2. Find existing patterns in the repo; follow local conventions.
3. Start from the closest template in assets/ and adapt.
4. Add ownership + review cadence for critical docs (runbooks, onboarding, API reference).
5. Run documentation QA (links, formatting, spelling, examples) before merging.

Decision Tree

User needs: [Documentation Task]
    ├─ New project? → **README.md**
    ├─ Technical decision? → **ADR**
    ├─ Building API? → **OpenAPI spec** + api-docs-template
    ├─ New version? → **CHANGELOG.md**
    ├─ Team collaboration? → **CONTRIBUTING.md**
    ├─ Documenting code? → **Docstrings** (JSDoc, Python)
    └─ Building docs site? → **MkDocs** (Python) or **Docusaurus** (JS)

Cross-Platform AI Documentation

AGENTS.md Standard

Prefer AGENTS.md as the cross-tool source of truth. If a specific tool requires a different filename (example: Claude Code uses CLAUDE.md), keep it aligned via a symlink only when you want identical content across tools.

# If `CLAUDE.md` does not exist and you want identical content:
ln -s AGENTS.md CLAUDE.md

Do / Avoid

Do

• Assign owners and review cadences to critical docs
• Add CI checks for links, style, and staleness
• Prefer small, task-oriented docs over big wiki pages
• Use Keep a Changelog format with semantic versioning

Avoid

• Docs without owners (guaranteed to rot)
• Stale runbooks (dangerous during incidents)
• Copy/paste docs that drift from code

Resources

Templates

Related Skills