概述
中文技术文档常见的问题往往不是内容不足，而是读起来别扭——中英文挤在一起没有空格、全角半角混用、带有明显机翻痕迹。本技能提供一套中文技术文档写作规范，用于提升文档的可读性与一致性。
核心原则：排版服务于阅读体验，规范服务于一致性，内容服务于读者。参考标准为「中文文案排版指北」。调用方式：仅在用户显式输入 /chinese-documentation 时调用，不根据上下文自动触发。
排版规范
空格
- 中英文之间加空格（如「使用 Git 进行版本管理，配合 Jenkins 实现持续集成」）。
- 中文与数字之间加空格（如「本次更新包含 3 个新功能和 12 个 Bug 修复」）。
- 数字与单位之间加空格（如「文件大小不超过 5 MB，响应时间控制在 200 ms 以内」）。
- 例外：度数、百分比等不加空格（如「今天气温 32°C，CPU 使用率 95%」）。
- 链接前后加空格（如「请参考 官方文档 获取更多信息」）。
标点符号
- 中文语境使用全角标点（如「注意：该接口需要鉴权，请先获取 Token」）。
- 全角标点与英文或数字之间不加空格。
- 括号：中文语境用全角括号；括号内有英文或数字时用半角括号；纯英文内容用半角括号。
- 引号：中文推荐使用直角引号，也可按团队规范使用弯引号；嵌套引号示例为「他说：『请点击确定按钮』」。
数字
- 技术文档中统一使用半角阿拉伯数字，不使用中文数字描述技术参数（如「支持最多 100 个并发连接」，而非「一百个」）。
- 版本号、端口号、HTTP 状态码等使用半角字符。
中英混排最佳实践
术语处理原则
保留英文的情况：专有名词（React、Kubernetes、Redis、MySQL）、行业通用缩写（API、SDK、CLI、ORM、CI/CD）、命令和代码（npm install、git commit）、协议和标准（HTTP、TCP/IP、JSON、REST）、没有公认中文翻译的术语（debounce、throttle、middleware）。
翻译为中文的情况：有公认翻译的通用概念（数据库、服务器、浏览器、框架）、描述性短语（version control→版本控制，load balancing→负载均衡）、文档标题和章节名（尽量中文，技术名词可保留英文）。
首次出现标注翻译
技术术语首次出现时标注中英对照，例如「消息队列（Message Queue）」「死信队列（Dead Letter Queue）」，后续出现可直接使用中文。
避免过度翻译
保留业界通用英文术语，例如「在 Controller 层做参数校验，Service 层处理业务逻辑」「使用 Redis 做 Session 缓存」，避免强行翻译成难以理解的表述。
API 文档中英对照格式
接口文档模板包含：
- 基本信息：请求方式、请求路径、鉴权方式、Content-Type。
- 请求参数表：字段名、类型、是否必填、说明（中英对照）。
- 请求示例（JSON）。
- 响应参数表与响应示例（JSON）。
- 错误码表：错误码、说明、处理建议。
- 金额表示约定：明确说明单位，例如 total_amount: 9900 单位为分（即 99.00 元），避免用浮点数造成歧义。
README.md 中文模板
国内开源项目常用结构：项目名称与徽章、一句话简介、特性列表、快速开始（环境要求、安装命令、基本用法代码）、文档链接、示例、贡献指南（含本地开发的克隆、安装依赖、启动开发服务器、运行测试命令）、致谢、许可证。
常见问题与避坑指南
- 机翻味：避免被动语态、冗余代词与直译英文句式。
- 句式欧化：长句拆短句，把定语从句改为并列句，一句话只说一件事。
- 过度翻译：保留通用术语原文，如「请打开终端，运行 npm install」。
- 中英标点混用：中文句子用全角标点，英文内容用半角标点。
- 缺乏结构化：用列表和分段组织信息，例如把缓存策略拆成存储层、写入流程、读取流程、缓存过期等条目。
写作检查清单
发布文档前逐项检查：
- 排版：中英文之间有空格、中文与数字之间有空格、中文语境用全角标点、英文与代码部分用半角标点、无全角半角混用。
- 术语：专有名词保留英文原文、首次出现的术语标注中英对照、无过度翻译、术语使用前后一致。
- 内容：句子简短无欧化长句、无不必要的被动语态、用列表和表格组织信息、代码示例可直接运行、无机翻味。
- 格式：标题层级正确不跳级、代码块标注语言类型、链接可正常访问、图片有 alt 文本。