Chinese Documentation

jnMetaCode/superpowers-zh/skills/chinese-documentation

作者 jnMetaCode2daf57c0fb157521de24c62ac9c3254630eefbedMIT收录于 2026年10月9日更新于 2026年10月9日

中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。

仅含说明Writing & Content
AI 生成的概览

中文技术文档排版参考，涵盖中英文空格、全半角标点与术语约定。

功能
提供中文技术文档的写作规范：中英文与数字之间的空格、全角与半角标点的使用、括号与引号写法、数字用法。还包含中英混排的术语处理原则、中英对照的 API 文档模板、中文 README 模板、机翻味与欧化句式等常见问题，以及发布前的检查清单。该技能仅为说明性参考，不生成文件，也不包含脚本。
适用场景
在撰写、编辑或审校中文技术文档、README 或 API 参考，并需要统一排版与术语时使用。该技能设计为由用户显式调用，而非根据上下文自动触发。
运行要求
无需任何工具、依赖包或凭据，仅为纯文本参考。文中引用了一份外部排版规范作为标准，但运行时不需联网。

中文技术文档写作规范

概述

中文技术文档最常见的问题不是内容不够，而是读起来别扭——中英文挤在一起没有空格、全角半角混用、一股机翻味。本技能提供一套完整的中文技术文档写作规范，让你的文档专业、好读、不出戏。

核心原则： 排版服务于阅读体验，规范服务于一致性，内容服务于读者。

参考标准： 中文文案排版指北

中文排版规范

空格

中英文之间加空格：

# 好使用 Git 进行版本管理，配合 Jenkins 实现持续集成。
# 坏使用Git进行版本管理，配合Jenkins实现持续集成。

中文与数字之间加空格：

# 好本次更新包含 3 个新功能和 12 个 Bug 修复。
# 坏本次更新包含3个新功能和12个Bug修复。

数字与单位之间加空格：

# 好文件大小不超过 5 MB，响应时间控制在 200 ms 以内。
# 坏文件大小不超过5MB，响应时间控制在200ms以内。

例外：度数、百分比等不加空格：

# 好今天气温 32°C，CPU 使用率 95%。
# 坏今天气温 32 °C，CPU 使用率 95 %。

链接前后加空格：

# 好请参考 [官方文档](https://example.com) 获取更多信息。
# 坏请参考[官方文档](https://example.com)获取更多信息。

标点符号

中文语境使用全角标点：

# 好注意：该接口需要鉴权，请先获取 Token。
# 坏注意:该接口需要鉴权,请先获取 Token.

全角标点与英文/数字之间不加空格：

# 好项目使用 MIT 协议，详见 LICENSE 文件。
# 坏项目使用 MIT 协议 ，详见 LICENSE 文件 。

括号的使用：

# 中文语境用全角括号请运行安装命令（详见下方说明）。
# 括号内有英文或数字时用半角括号该项目基于 Spring Boot (v3.2.0) 开发。
# 纯英文内容用半角括号See the documentation (README.md) for details.

引号的使用：

# 中文使用直角引号（推荐）「确定」按钮触发表单提交，「取消」按钮关闭弹窗。
# 也可以使用弯引号（视团队规范而定）"确定"按钮触发表单提交，"取消"按钮关闭弹窗。
# 嵌套引号他说：「请点击『确定』按钮。」

数字

# 阿拉伯数字（技术文档中统一使用半角数字）支持最多 100 个并发连接。
# 不要用中文数字写技术参数# 坏：支持最多一百个并发连接。
# 数字使用半角字符版本号 v2.1.0，端口号 8080，HTTP 状态码 200。

中英混排最佳实践

术语处理原则

保留英文的情况：

  • 专有名词：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 文档中英对照格式

接口文档模板

markdown
## 创建订单 / Create Order
### 基本信息
- **请求方式 (Method):** POST- **请求路径 (Path):** `/api/v1/orders`- **鉴权方式 (Auth):** Bearer Token- **Content-Type:** application/json
### 请求参数 (Request Parameters)
| 参数名 (Field) | 类型 (Type) | 必填 (Required) | 说明 (Description) ||----------------|-------------|-----------------|-------------------|| product_id | string | 是 | 商品 ID (Product ID) || quantity | integer | 是 | 购买数量 (Quantity)，最小值为 1 || address_id | string | 是 | 收货地址 ID (Shipping address ID) || coupon_code | string | 否 | 优惠券码 (Coupon code) |
### 请求示例 (Request Example)
\```json{  "product_id": "prod_abc123",  "quantity": 2,  "address_id": "addr_xyz789",  "coupon_code": "SUMMER2024"}\```
### 响应参数 (Response Parameters)
| 参数名 (Field) | 类型 (Type) | 说明 (Description) ||----------------|-------------|-------------------|| order_id | string | 订单 ID (Order ID) || status | string | 订单状态 (Order status): pending / paid / shipped || total_amount | integer | 订单总金额，单位：分 (Total amount in cents) || created_at | string | 创建时间 (Created at)，ISO 8601 格式 |
### 响应示例 (Response Example)
\```json{  "code": 0,  "message": "success",  "data": {    "order_id": "ord_20240315001",    "status": "pending",    "total_amount": 9900,    "created_at": "2024-03-15T10:30:00+08:00"  }}\```
### 错误码 (Error Codes)
| 错误码 (Code) | 说明 (Description) | 处理建议 (Suggestion) ||---------------|--------------------|--------------------|| 40001 | 商品不存在 (Product not found) | 检查 product_id 是否正确 || 40002 | 库存不足 (Insufficient stock) | 减少购买数量或稍后重试 || 40003 | 优惠券已过期 (Coupon expired) | 移除 coupon_code 或更换优惠券 |

金额表示约定

# 好：明确说明单位total_amount: 9900  // 单位：分（即 99.00 元）
# 坏：不说明单位，造成歧义total_amount: 99.00  // 是元还是分？浮点数会有精度问题

README.md 中文模板

国内开源项目常用的 README 结构：

markdown
# 项目名称
[![License](https://img.shields.io/badge/license-MIT-blue.svg)]()[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
简短一句话介绍项目是什么、解决什么问题。
## 特性
- 特性一：简要描述- 特性二：简要描述- 特性三：简要描述
## 快速开始
### 环境要求
- Node.js >= 20- MySQL >= 8.0
### 安装
\```bashnpm install your-package\```
### 基本用法
\```typescriptimport { YourPackage } from 'your-package';
const client = new YourPackage({ apiKey: 'your-key' });const result = await client.doSomething();\```
## 文档
- [使用指南](./docs/guide.md)- [API 参考](./docs/api.md)- [常见问题](./docs/faq.md)- [更新日志](./CHANGELOG.md)
## 示例
更多示例请查看 [examples](./examples) 目录。
## 贡献指南
欢迎提交 Issue 和 Pull Request。请先阅读 [贡献指南](./CONTRIBUTING.md)。
### 本地开发
\```bash# 克隆项目git clone https://gitee.com/your-org/your-project.git
# 安装依赖npm install
# 启动开发服务器npm run dev
# 运行测试npm test\```
## 致谢
- [依赖项目一](https://example.com) — 简要说明- [依赖项目二](https://example.com) — 简要说明
## 许可证
[MIT](./LICENSE)

常见问题与避坑指南

问题一：机翻味

特征： 句式生硬、不符合中文表达习惯。

# 机翻味这个函数被用来计算用户的折扣。如果你想要获取更多信息，请参考文档。
# 自然中文这个函数用于计算用户折扣。更多信息请参考文档。

要点：

  • 避免被动语态（"被用来" → "用于"）
  • 避免冗余代词（"你想要" → 直接说）
  • 避免直译英文句式

问题二：句式欧化

特征： 长定语、多重从句、一句话说不完。

# 欧化句式这是一个可以帮助开发者在不需要手动配置复杂的构建工具链的情况下快速搭建现代化前端项目的脚手架工具。
# 正常中文这是一个前端脚手架工具，帮助开发者快速搭建项目，免去手动配置构建工具链的麻烦。

要点：

  • 长句拆成短句
  • 把定语从句改成并列句
  • 一句话只说一件事

问题三：过度翻译

# 过度翻译请打开您的"终端模拟器"，运行"节点包管理器"的安装命令。
# 正常写法请打开终端，运行 npm install。

问题四：中英标点混用

# 坏：中文句子用了英文逗号和句号请先安装依赖,然后运行测试.
# 好：中文句子用全角标点请先安装依赖，然后运行测试。
# 坏：英文内容用了中文标点Run `npm install`，then `npm test`。
# 好：英文内容用半角标点Run `npm install`, then `npm test`.

问题五：缺乏结构化

# 坏：一大段文字没有分段本系统使用 Redis 做缓存提高查询性能同时使用 MySQL 做持久化存储数据写入时先写 MySQL 再异步更新 Redis 缓存读取时先查 Redis 如果未命中再查 MySQL 并将结果回写缓存设置过期时间为 30 分钟……
# 好：用列表和分段组织信息本系统的缓存策略如下：
- **存储层：** MySQL（持久化）+ Redis（缓存）- **写入流程：** 先写 MySQL，再异步更新 Redis- **读取流程：** 先查 Redis → 未命中则查 MySQL → 回写 Redis- **缓存过期：** TTL 设为 30 分钟

写作检查清单

在发布文档前，逐项检查：

排版

  • 中英文之间有空格
  • 中文与数字之间有空格
  • 中文语境使用全角标点
  • 英文/代码部分使用半角标点
  • 没有全角半角标点混用

术语

  • 专有名词保留英文原文
  • 首次出现的术语标注了中英对照
  • 没有过度翻译业界通用术语
  • 术语使用前后一致

内容

  • 句子简短，没有欧化长句
  • 没有不必要的被动语态
  • 用列表和表格组织结构化信息
  • 代码示例可以直接运行
  • 没有"机翻味"

格式

  • 标题层级正确（不跳级）
  • 代码块标注了语言类型
  • 链接可以正常访问
  • 图片有 alt 文本

来源与署名

来源：jnMetaCode/superpowers-zh位于skills/chinese-documentation提交2daf57c

许可证： MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 jnMetaCode/superpowers-zh 的技能

Using Superpowers

jnMetaCode

元技能：确立在任何响应前查找并调用技能的方式，并提供各平台工具参考。

AI & Agents2026年10月9日

Writing Plans

jnMetaCode

在动手写代码之前，为多步骤编码任务编写详细的逐步实现计划。

Productivity & Workflow2026年10月9日

Verification Before Completion

jnMetaCode

要求在宣称任务完成、已修复或测试通过之前，先运行新的验证命令并引用其输出。

Software Development2026年10月9日

Using Git Worktrees

jnMetaCode

为功能开发建立隔离的 Git 工作树，优先使用原生工具，否则回退到 git worktree。

Software Development2026年10月9日

Test Driven Development

jnMetaCode

指导智能体严格遵循测试驱动开发：先写会失败的测试，再写最少代码，最后重构。

Software Development2026年10月9日

Requesting Code Review

jnMetaCode

派遣代码审查子代理，用组织好的上下文在合并前验证已完成的工作。

Software Development2026年10月9日

更多Writing & Content技能

Doc Coauthoring

anthropics

精选

引导用户通过三阶段工作流协作撰写文档、提案、技术规格与决策文档。

Writing & Content180K今天更新

Writing Guidelines

vercel-labs

精选

依据获取的写作指南审查文档与文稿，并报告风格问题。

Writing & Content32K5周前更新

Job Post Builder

anthropics

精选

根据职位需求生成招聘材料包：职位发布、面试指南与评分表、录用通知书模板。

Writing & Content27K今天更新

Write Spec

anthropics

精选

把功能想法或问题陈述转化为结构化 PRD，包含目标、用户故事、需求与指标。

Writing & Content27K今天更新

Draft Content

anthropics

精选

撰写博客文章、社交媒体帖文、邮件通讯、落地页、新闻稿和案例研究等营销内容。

Writing & Content27K今天更新

Brand Voice Enforcement

anthropics

精选

将现有品牌语调指南应用于销售和营销内容，并说明所采用的品牌选择。

Writing & Content27K今天更新