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 Documentation Type Template When to Use Project README readme-template.md New project, onboarding Architecture Decision adr-template.md Technical decisions API Reference api-docs-template.md REST/GraphQL APIs Changelog changelog-template.md Version history Contributing Guide contributing-template.md Open source, teams Workflow Identify the documentation type and audience. Find existing patterns in the repo; follow local conventions. Start from the closest template in assets/ and adapt. Add ownership + review cadence for critical docs (runbooks, onboarding, API reference). 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 Resource Purpose references/readme-best-practices.md README structure, badges references/adr-writing-guide.md ADR lifecycle, examples references/changelog-best-practices.md Keep a Changelog format references/api-documentation-standards.md REST, GraphQL, gRPC docs references/code-commenting-guide.md Docstrings, inline comments references/contributing-guide-standards.md CONTRIBUTING.md structure references/docs-as-code-setup.md MkDocs, Docusaurus, CI/CD references/writing-best-practices.md Clear communication references/markdown-style-guide.md Markdown formatting references/documentation-testing.md Vale, markdownlint, cspell references/ai-documentation-tools.md Mintlify, DocuWriter, GEO references/production-gotchas-guide.md Documenting platform issues Templates Category Templates Architecture adr-template.md API Reference api-docs-template.md Project Management readme-template.md, changelog-template.md, contributing-template.md Docs-as-Code docs-structure-template.md, ownership-model.md Related Skills Skill Purpose qa-docs-coverage Documentation gap audit dev-api-design REST API patterns git-workflow Conventional Commits docs-ai-prd PRD templates