---
name: yangge521/tech-doc-cn
source: https://app.decimal.ai/s/yangge521-tech-doc-cn@1/SKILL.md
source_sha256: 39980f48fbfa
---

# 中文技术文档写作

## 概述

提供中文技术文档的写作规范和模板，涵盖 API 文档、架构设计文档、部署运维文档，帮助团队产出高质量技术文档。

## 使用场景

- API 接口文档：为推理 API 编写接口文档
- 架构设计文档：系统设计方案评审
- 部署运维手册：GPU 推理服务部署文档
- 技术方案：项目立项和方案评审
- 事故复盘：故障分析和复盘报告
- 用户指南：产品使用说明

## 写作规范

### 1. 文档结构

技术文档应包含：标题、版本历史、概述、目录、正文、附录。正文按"是什么-为什么-怎么做"组织。

### 2. API 文档模板

API 文档包含：接口名称、请求方法、URL、请求参数（表格：参数名/类型/必填/说明）、响应格式（JSON 示例）、错误码表、curl 和 Python 调用示例。

### 3. 架构文档模板

架构文档包含：系统背景、架构图（Mermaid）、模块说明、数据流图、技术选型理由、性能指标、扩展方案。

### 4. 部署文档模板

部署文档包含：环境要求、依赖安装、配置说明、启动命令、健康检查、常见问题排查。每步提供可复制命令。

### 5. 写作风格

- 简洁中文，避免翻译腔
- 技术术语保留英文（GPU、FPS、Batch Size）
- 代码示例确保可运行
- 表格优于长段落
- 关键信息加粗

## 常见问题与排查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 文档过时 | 未及时更新 | CI 检查文档与代码同步 |
| 代码示例不可运行 | 复制粘贴错误 | 实际运行验证 |
| 架构图不清晰 | 工具不熟练 | 使用 Mermaid 语法 |
| 中英混杂 | 无统一规范 | 制定术语表 |

## 扩展方向

- **文档即代码**: Markdown + Git 版本管理
- **自动生成**: 从代码注释生成 API 文档
- **交互式文档**: Swagger/Redoc 在线 API 文档
- **文档站点**: MkDocs/VitePress 搭建文档站
- **多语言**: 中英文双语文档
- **AI 辅助**: 使用 AI 自动生成文档初稿

## 技能链路

- **readme-generator**: README 文档生成
- **code-comment-cn**: 代码注释规范
- **meeting-notes**: 会议纪要文档
- **weekly-report**: 周报文档

## 检查清单

- [ ] 文档结构完整
- [ ] 代码示例可运行
- [ ] 表格信息清晰
- [ ] 版本历史已记录
- [ ] 无错别字和语法错误