docs-codebase
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTechnical 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.
可直接落地的清晰、可维护技术文档模式。
2026年1月现代最佳实践：文档即代码（docs-as-code）、文档归属+审核周期、文档质量检查关卡（链接/风格/拼写）、AI辅助撰写与审核、面向流式架构的OpenAPI 3.2.0、面向AI搜索的GEO（生成式引擎优化）。
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 |
| 文档类型 | 模板 | 适用场景 |
|---|---|---|
| 项目README | readme-template.md | 新项目、员工入职 |
| 架构决策记录 | adr-template.md | 技术决策留存 |
| API参考文档 | api-docs-template.md | REST/GraphQL API |
| 变更日志 | changelog-template.md | 版本历史记录 |
| 贡献指南 | contributing-template.md | 开源项目、团队协作 |
Workflow
工作流
- Identify the documentation type and audience.
- Find existing patterns in the repo; follow local conventions.
- Start from the closest template in and adapt.
assets/ - Add ownership + review cadence for critical docs (runbooks, onboarding, API reference).
- Run documentation QA (links, formatting, spelling, examples) before merging.
- 确定文档类型和受众。
- 查看仓库中已有的模式，遵循本地约定。
- 从目录下最匹配的模板开始，进行调整。
assets/ - 为关键文档（运行手册、入职文档、API参考）添加归属与审核周期。
- 合并前运行文档质量检查（链接、格式、拼写、示例）。
Decision Tree
决策树
text
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)text
用户需求：[文档任务]
├─ 新项目？→ **README.md**
├─ 技术决策？→ **ADR**
├─ 开发API？→ **OpenAPI 规范** + api-docs-template
├─ 新版本发布？→ **CHANGELOG.md**
├─ 团队协作？→ **CONTRIBUTING.md**
├─ 代码注释？→ **文档字符串**（JSDoc、Python）
└─ 搭建文档站点？→ **MkDocs**（Python）或 **Docusaurus**（JS）Cross-Platform AI Documentation
跨平台AI文档
AGENTS.md Standard
AGENTS.md 标准
Prefer as the cross-tool source of truth. If a specific tool requires a different filename (example: Claude Code uses ), keep it aligned via a symlink only when you want identical content across tools.
AGENTS.mdCLAUDE.mdbash
undefined优先将作为跨工具的事实来源。如果特定工具要求不同的文件名（例如：Claude Code 使用），仅当你希望跨工具内容完全一致时，通过符号链接保持对齐。
AGENTS.mdCLAUDE.mdbash
undefinedIf CLAUDE.md
does not exist and you want identical content:
CLAUDE.md如果CLAUDE.md
不存在且需要内容完全一致：
CLAUDE.mdln -s AGENTS.md CLAUDE.md
undefinedln -s AGENTS.md CLAUDE.md
undefinedDo / 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
- 为关键文档指定负责人和审核周期
- 添加CI检查，覆盖链接、格式和文档时效性
- 优先选择小型、面向任务的文档，而非大型维基页面
- 使用「Keep a Changelog」格式配合语义化版本控制
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 |
| 资源 | 用途 |
|---|---|
| references/readme-best-practices.md | README结构、徽章使用 |
| references/adr-writing-guide.md | ADR生命周期、示例 |
| references/changelog-best-practices.md | Keep a Changelog格式指南 |
| references/api-documentation-standards.md | REST、GraphQL、gRPC文档规范 |
| references/code-commenting-guide.md | 文档字符串、行内注释 |
| references/contributing-guide-standards.md | CONTRIBUTING.md结构规范 |
| references/docs-as-code-setup.md | MkDocs、Docusaurus、CI/CD配置 |
| references/writing-best-practices.md | 清晰沟通技巧 |
| references/markdown-style-guide.md | Markdown格式规范 |
| references/documentation-testing.md | Vale、markdownlint、cspell工具使用 |
| references/ai-documentation-tools.md | Mintlify、DocuWriter、GEO工具使用 |
| references/production-gotchas-guide.md | 平台问题文档化 |
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 |
| 分类 | 模板 |
|---|---|
| 架构 | adr-template.md |
| API参考 | api-docs-template.md |
| 项目管理 | readme-template.md, changelog-template.md, contributing-template.md |
| 文档即代码 | 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 |
| 技能 | 用途 |
|---|---|
| qa-docs-coverage | 文档缺口审计 |
| dev-api-design | REST API模式设计 |
| git-workflow | 规范化提交 |
| docs-ai-prd | PRD模板 |