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.

Docs Folder / LLM-Generated Revamp Mode (Any Repo)

Use this mode when a repo's docs/ folder contains substantial research notes for LLMs and implementation docs generated by LLMs.

• Build an inventory and classify each file by doc type (Tutorial , How-to , Reference , Explanation ).

• Mark lifecycle metadata for non-canonical files:

status: draft | canonical | integrated | superseded owner: @username last_verified: 2026-02-24 integrates_into: docs/path/to/canonical-doc.md delete_by: 2026-03-31

• For each topic/feature, keep exactly one canonical spec/reference and merge all duplicates into it.

• Keep only durable facts/decisions in canonical docs; move exploration detail to short linked evidence notes.

• Keep a compact LLM doc library with root anchors: AGENTS.md , README.md , and minimal canonical docs under docs/ (instructions , specs , reference-data ).

• Delete integrated drafts on schedule; avoid .archive/ mirrors in docs/ unless retention is mandatory.

Decision Tree

User needs: [Documentation Task] ├─ Repo has a docs folder with many LLM-generated docs? → Revamp Mode (inventory → canonicalize → trim) ├─ 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

LLM-First Documentation Patterns

When documentation is consumed primarily by AI agents (AGENTS.md, CLAUDE.md, canonical docs for coding assistants), stale docs become a distinct category of bug.

Stale Docs = Agent Bugs

An agent reading stale docs will:

• Attempt to fix problems that are already solved (e.g., "9 open gating gaps" that were all sealed)

• Use wrong model names (e.g., "Claude Haiku" when code uses gpt-4o )

• Apply wrong limits (e.g., "fully gated" when free tier actually gets 3/week)

• Re-implement features that already exist

Rule: Treat doc updates as part of the feature PR, not as a follow-up task.

Report Integration Lifecycle

Temporary investigation docs (QA reports, research exports, audit findings) must not become permanent false sources of truth.

Every dated report file must carry lifecycle metadata:

Status: pending-integration | integrated | superseded Integrates-into: docs/product/pricing-feature-matrix.md Owner: @username Delete-by: 2026-03-15

Workflow:

• Create report with Status: pending-integration

• Extract durable findings into canonical docs

• Mark report Status: integrated with date

• Delete after Delete-by date (git history preserves everything)

Living Docs: Audit Tables with Status Columns

Instead of deleting audit findings, add a Status column:

Gap Status Sealed In

Chart aspects visible to free Sealed PR #26

Dreams unlimited for free Sealed PR #26

Ask Cosmos no rate limit Open —

This preserves the audit trail while showing current state. Agents can quickly scan for Open items.

Two-Pass Consolidation

When consolidating planning docs into canonical docs:

• First pass: Follow the plan — extract content, delete source files, fix cross-references

• Second pass: Audit deleted content against canonical destinations

• git show deleted files to recover any unique data missed in planning

• Compare code to docs for drift (e.g., feature marked "Planned" but code shows it's implemented)

Even thorough consolidation plans miss unique data that only lived in one source doc.

Canonical Set Rule (No Doc Sprawl)

• One subject/feature should have one canonical doc.

• Derived docs must link to canonical docs instead of restating them.

• If a derived doc is fully integrated, mark it integrated and remove it by delete_by (default: delete, not archive).

• If two canonical docs overlap, merge and leave a redirect note in the removed file path.

Canonical LLM Library Rule

• Root files are mandatory anchors: AGENTS.md for agent behavior/instructions and README.md for project navigation.

• The docs/ folder should expose only a small canonical set for LLM consumption: current instruction sets, current specs, and durable reference data.

• Research logs, exploratory prompts, and intermediate drafts are temporary working files, not library entries.

• Keep discovery breadcrumbs as links from canonical docs; do not duplicate full research dumps.

Anti-Fluff Rewrite Gate

Before merging LLM-generated docs, require:

• explicit audience and decision/use-case for each section

• measurable statements instead of vague claims

• source links + dates for external facts

• removal of duplicated paragraphs and "future ideas" not tied to a tracked decision

Staleness Disclaimers Over Wrong Numbers

For externally-sourced data (competitor pricing, API rate limits, third-party capabilities):

Prices as of Feb 2026 — verify current pricing at [source].

A staleness disclaimer is safer than a potentially wrong number. Wrong numbers in agent-consumed docs cause incorrect implementation decisions.

Decision Log Collision Prevention

When adding entries to a decision log (e.g., ### D039 — Feature Name ):

Always check the latest entry number before adding

grep -o '### D[0-9]*' docs/decision-log.md | tail -1

Numbering collisions happen when two decisions are logged in rapid succession without checking.

Backlog Status Sync Pattern (Mandatory)

When implementation status changes (for example backlog milestones completed), sync canonical docs in the same delivery cycle to prevent stale guidance for humans and agents.

Sync Rules

• Update one canonical status source first (feature matrix / roadmap / decision log).

• Propagate only by reference links in secondary docs; avoid duplicate status prose.

• Add concrete completion dates and owner for status changes.

• If temporary reports are integrated, mark lifecycle state (integrated or superseded ) and delete_by .

Release Gate

A feature is not doc-complete until:

• canonical status doc updated,

• dependent docs checked for conflicting claims,

• docs sync checklist completed.

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

references/documentation-metrics.md Doc quality, freshness, coverage scoring

references/onboarding-documentation.md Developer ramp-up guides, Day 1-Week 4

references/runbook-writing-guide.md Operational runbooks, incident response

references/backlog-status-sync-pattern.md Canonical backlog status sync workflow for multi-doc repos

Templates

Category Templates

Architecture adr-template.md

API Reference api-docs-template.md

Project Management readme-template.md, changelog-template.md, contributing-template.md

Documentation Lifecycle template-doc-sync-checklist.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

dev-git-workflow Conventional Commits

docs-ai-prd PRD templates

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.

• Prefer primary sources; report source links and dates for volatile information.

• If web access is unavailable, state the limitation and mark guidance as unverified.