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.

docs-codebase