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
1---
2name: docs-codebase
3description: Technical writing patterns for README files, API documentation, architecture decision records (ADRs), changelogs, contributing guides, code comments, and docs-as-code workflows. Covers documentation structure, style guides, Markdown best practices, and documentation testing.
4---
5
6# Technical Documentation
7
8Execution-ready patterns for clear, maintainable technical documentation.
9
10**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.
11
12## Quick Reference
13
14| Documentation Type | Template | When to Use |
15|-------------------|----------|-------------|
16| **Project README** | [readme-template.md](assets/project-management/readme-template.md) | New project, onboarding |
17| **Architecture Decision** | [adr-template.md](assets/architecture/adr-template.md) | Technical decisions |
18| **API Reference** | [api-docs-template.md](assets/api-reference/api-docs-template.md) | REST/GraphQL APIs |
19| **Changelog** | [changelog-template.md](assets/project-management/changelog-template.md) | Version history |
20| **Contributing Guide** | [contributing-template.md](assets/project-management/contributing-template.md) | Open source, teams |
21
22## Workflow
23
241. Identify the documentation type and audience.
252. Find existing patterns in the repo; follow local conventions.
263. Start from the closest template in `assets/` and adapt.
274. Add ownership + review cadence for critical docs (runbooks, onboarding, API reference).
285. Run documentation QA (links, formatting, spelling, examples) before merging.
29
30## Decision Tree
31
32```text
33User needs: [Documentation Task]
34 ├─ New project? → **README.md**
35 ├─ Technical decision? → **ADR**
36 ├─ Building API? → **OpenAPI spec** + api-docs-template
37 ├─ New version? → **CHANGELOG.md**
38 ├─ Team collaboration? → **CONTRIBUTING.md**
39 ├─ Documenting code? → **Docstrings** (JSDoc, Python)
40 └─ Building docs site? → **MkDocs** (Python) or **Docusaurus** (JS)
41```
42
43## Cross-Platform AI Documentation
44
45### AGENTS.md Standard
46
47Prefer `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.
48
49```bash
50# If `CLAUDE.md` does not exist and you want identical content:
51ln -s AGENTS.md CLAUDE.md
52```
53
54## Do / Avoid
55
56### Do
57
58- Assign owners and review cadences to critical docs
59- Add CI checks for links, style, and staleness
60- Prefer small, task-oriented docs over big wiki pages
61- Use Keep a Changelog format with semantic versioning
62
63### Avoid
64
65- Docs without owners (guaranteed to rot)
66- Stale runbooks (dangerous during incidents)
67- Copy/paste docs that drift from code
68
69## Resources
70
71| Resource | Purpose |
72|----------|---------|
73| [references/readme-best-practices.md](references/readme-best-practices.md) | README structure, badges |
74| [references/adr-writing-guide.md](references/adr-writing-guide.md) | ADR lifecycle, examples |
75| [references/changelog-best-practices.md](references/changelog-best-practices.md) | Keep a Changelog format |
76| [references/api-documentation-standards.md](references/api-documentation-standards.md) | REST, GraphQL, gRPC docs |
77| [references/code-commenting-guide.md](references/code-commenting-guide.md) | Docstrings, inline comments |
78| [references/contributing-guide-standards.md](references/contributing-guide-standards.md) | CONTRIBUTING.md structure |
79| [references/docs-as-code-setup.md](references/docs-as-code-setup.md) | MkDocs, Docusaurus, CI/CD |
80| [references/writing-best-practices.md](references/writing-best-practices.md) | Clear communication |
81| [references/markdown-style-guide.md](references/markdown-style-guide.md) | Markdown formatting |
82| [references/documentation-testing.md](references/documentation-testing.md) | Vale, markdownlint, cspell |
83| [references/ai-documentation-tools.md](references/ai-documentation-tools.md) | Mintlify, DocuWriter, GEO |
84| [references/production-gotchas-guide.md](references/production-gotchas-guide.md) | Documenting platform issues |
85
86## Templates
87
88| Category | Templates |
89|----------|-----------|
90| Architecture | [adr-template.md](assets/architecture/adr-template.md) |
91| API Reference | [api-docs-template.md](assets/api-reference/api-docs-template.md) |
92| Project Management | [readme-template.md](assets/project-management/readme-template.md), [changelog-template.md](assets/project-management/changelog-template.md), [contributing-template.md](assets/project-management/contributing-template.md) |
93| Docs-as-Code | [docs-structure-template.md](assets/docs-as-code/docs-structure-template.md), [ownership-model.md](assets/docs-as-code/ownership-model.md) |
94
95## Related Skills
96
97| Skill | Purpose |
98|-------|---------|
99| [qa-docs-coverage](../qa-docs-coverage/SKILL.md) | Documentation gap audit |
100| [dev-api-design](../dev-api-design/SKILL.md) | REST API patterns |
101| [git-workflow](../git-workflow/SKILL.md) | Conventional Commits |
102| [docs-ai-prd](../docs-ai-prd/SKILL.md) | PRD templates |
majiayu000