中文技术文档写作规范

Chinese Technical Documentation Writing Guidelines

概述

Overview

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

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

The most common problem with Chinese technical documentation isn't insufficient content, but awkward readability—no spaces between Chinese and English characters, mixed full-width and half-width characters, and a strong machine translation vibe. This skill provides a complete set of Chinese technical documentation writing guidelines to make your documents professional, easy to read, and natural.

Core Principles: Formatting serves reading experience, standards serve consistency, and content serves readers.

Reference Standard: Chinese Copywriting Guidelines

中文排版规范

Chinese Formatting Standards

空格

Spaces

中英文之间加空格：

undefined

Add spaces between Chinese and English:

undefined

好

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

坏

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


**中文与数字之间加空格：**

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


**Add spaces between Chinese and numbers:**

好

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

坏

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


**数字与单位之间加空格：**

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


**Add spaces between numbers and units:**

好

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

坏

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


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

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


**Exceptions:** No spaces for degrees, percentages, etc.:

好

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

坏

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


**链接前后加空格：**

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


**Add spaces around links:**

好

请参考官方文档获取更多信息。

坏

请参考官方文档获取更多信息。

undefined

请参考官方文档获取更多信息。

undefined

标点符号

Punctuation

中文语境使用全角标点：

undefined

Use full-width punctuation in Chinese context:

undefined

好

注意：该接口需要鉴权，请先获取 Token。

坏

注意:该接口需要鉴权,请先获取 Token.


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

注意:该接口需要鉴权,请先获取 Token.


**No spaces between full-width punctuation and English/numbers:**

好

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

坏

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


**括号的使用：**

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


**Usage of parentheses:**

中文语境用全角括号

Use full-width parentheses in Chinese context

请运行安装命令（详见下方说明）。

括号内有英文或数字时用半角括号

Use half-width parentheses when containing English or numbers

该项目基于 Spring Boot (v3.2.0) 开发。

纯英文内容用半角括号

Use half-width parentheses for pure English content

See the documentation (README.md) for details.


**引号的使用：**

See the documentation (README.md) for details.


**Usage of quotation marks:**

中文使用直角引号（推荐）

Use right-angle quotation marks for Chinese (recommended)

「确定」按钮触发表单提交，「取消」按钮关闭弹窗。

也可以使用弯引号（视团队规范而定）

Curved quotation marks are also acceptable (subject to team standards)

"确定"按钮触发表单提交，"取消"按钮关闭弹窗。

嵌套引号

Nested quotation marks

他说：「请点击『确定』按钮。」

undefined

他说：「请点击『确定』按钮。」

undefined

数字

Numbers

undefined

undefined

阿拉伯数字（技术文档中统一使用半角数字）

Arabic numerals (use half-width numerals uniformly in technical documentation)

支持最多 100 个并发连接。

不要用中文数字写技术参数

Do not use Chinese numerals for technical parameters

坏：支持最多一百个并发连接。

Bad: 支持最多一百个并发连接。

数字使用半角字符

Use half-width characters for numbers

版本号 v2.1.0，端口号 8080，HTTP 状态码 200。

undefined

版本号 v2.1.0，端口号 8080，HTTP 状态码 200。

undefined

中英混排最佳实践

Best Practices for Mixed Chinese-English Layout

术语处理原则

Terminology Handling Principles

保留英文的情况：

专有名词：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 → 负载均衡
文档标题和章节名（尽量中文，技术名词可保留英文）

Cases where English should be retained:

Proper nouns: React, Kubernetes, Redis, MySQL
Industry通用缩写：API, SDK, CLI, ORM, CI/CD
Commands and code:
```
npm install
```
,
```
git commit
```
Protocols and standards: HTTP, TCP/IP, JSON, REST
Terms without widely accepted Chinese translations: debounce, throttle, middleware

Cases where translation to Chinese is required:

General concepts with widely accepted translations: 数据库 (database), 服务器 (server), 浏览器 (browser), 框架 (framework)
Descriptive phrases: version control → 版本控制, load balancing → 负载均衡
Document titles and section names (preferably in Chinese, technical terms can be retained in English)

首次出现标注翻译

Add Chinese-English annotations on first occurrence

技术术语首次出现时，标注中英对照：

undefined

Add Chinese-English annotations when technical terms appear for the first time:

undefined

好

本系统采用消息队列（Message Queue）实现异步通信，使用死信队列（Dead Letter Queue）处理消费失败的消息。

后续出现直接使用

Use directly in subsequent occurrences

消息队列的消费者需要实现幂等性……

undefined

消息队列的消费者需要实现幂等性……

undefined

避免过度翻译

Avoid over-translation

undefined

undefined

好：保留业界通用英文术语

Good: Retain industry-standard English terms

在 Controller 层做参数校验，Service 层处理业务逻辑。

坏：强行翻译反而看不懂

Bad: Forced translation makes it hard to understand

在控制器层做参数校验，服务层处理业务逻辑。

好

Good

使用 Redis 做 Session 缓存。

坏

Bad

使用"远程字典服务"做"会话"缓存。

undefined

使用"远程字典服务"做"会话"缓存。

undefined

API 文档中英对照格式

Chinese-English Format for API Documentation

接口文档模板

API Documentation Template

markdown

undefined

markdown

undefined

创建订单 / Create Order

基本信息

请求方式 (Method): POST
请求路径 (Path):
```
/api/v1/orders
```
鉴权方式 (Auth): Bearer Token
Content-Type: application/json

请求方式 (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)

参数名 (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 格式

参数名 (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 或更换优惠券

undefined

错误码 (Code)	说明 (Description)	处理建议 (Suggestion)
40001	商品不存在 (Product not found)	检查 product_id 是否正确
40002	库存不足 (Insufficient stock)	减少购买数量或稍后重试
40003	优惠券已过期 (Coupon expired)	移除 coupon_code 或更换优惠券

undefined

金额表示约定

Convention for Amount Representation

undefined

undefined

好：明确说明单位

Good: Clearly specify the unit

total_amount: 9900 // 单位：分（即 99.00 元）

坏：不说明单位，造成歧义

Bad: No unit specified, causing ambiguity

total_amount: 99.00 // 是元还是分？浮点数会有精度问题

undefined

total_amount: 99.00 // Is it yuan or cents? Floating-point numbers have precision issues

undefined

README.md 中文模板

Chinese README.md Template

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

markdown

undefined

Common README structure for domestic open-source projects:

markdown

undefined

项目名称

简短一句话介绍项目是什么、解决什么问题。

特性

特性一：简要描述
特性二：简要描述
特性三：简要描述

特性一：简要描述
特性二：简要描述
特性三：简要描述

快速开始

环境要求

Node.js >= 20
MySQL >= 8.0

Node.js >= 20
MySQL >= 8.0

安装

```bash npm install your-package ```

基本用法

```typescript import { YourPackage } from 'your-package';

const client = new YourPackage({ apiKey: 'your-key' }); const result = await client.doSomething(); ```

```typescript import { YourPackage } from 'your-package';

const client = new YourPackage({ apiKey: 'your-key' }); const result = await client.doSomething(); ```

文档

使用指南
API 参考
常见问题
更新日志

使用指南
API 参考
常见问题
更新日志

示例

更多示例请查看 examples 目录。

贡献指南

欢迎提交 Issue 和 Pull Request。请先阅读贡献指南。

本地开发

```bash

克隆项目

git clone https://gitee.com/your-org/your-project.git

安装依赖

npm install

启动开发服务器

npm run dev

运行测试

npm test ```

致谢

依赖项目一 — 简要说明
依赖项目二 — 简要说明

依赖项目一 — 简要说明
依赖项目二 — 简要说明

许可证

MIT

undefined

MIT

undefined

常见问题与避坑指南

Common Issues and Pitfall Avoidance Guide

问题一：机翻味

Issue 1: Machine Translation Vibe

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

undefined

Symptoms: Stiff sentence structure, inconsistent with Chinese expression habits.

undefined

机翻味

这个函数被用来计算用户的折扣。如果你想要获取更多信息，请参考文档。

自然中文

这个函数用于计算用户折扣。更多信息请参考文档。


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

这个函数用于计算用户折扣。更多信息请参考文档。


**Key Points:**
- Avoid passive voice ("被用来" → "用于")
- Avoid redundant pronouns ("你想要" → omit)
- Avoid literal translation of English sentence structures

问题二：句式欧化

Issue 2: Europeanized Sentence Structure

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

undefined

Symptoms: Long attributives, multiple clauses, overly long sentences.

undefined

欧化句式

这是一个可以帮助开发者在不需要手动配置复杂的构建工具链的情况下快速搭建现代化前端项目的脚手架工具。

正常中文

这是一个前端脚手架工具，帮助开发者快速搭建项目，免去手动配置构建工具链的麻烦。


**要点：**
- 长句拆成短句
- 把定语从句改成并列句
- 一句话只说一件事

这是一个前端脚手架工具，帮助开发者快速搭建项目，免去手动配置构建工具链的麻烦。


**Key Points:**
- Split long sentences into short ones
- Convert attributive clauses to coordinate clauses
- Focus on one idea per sentence

问题三：过度翻译

Issue 3: Over-translation

undefined

undefined

过度翻译

请打开您的"终端模拟器"，运行"节点包管理器"的安装命令。

正常写法

请打开终端，运行 npm install。

undefined

请打开终端，运行 npm install。

undefined

问题四：中英标点混用

Issue 4: Mixed Chinese and English Punctuation

undefined

undefined

坏：中文句子用了英文逗号和句号

Bad: Chinese sentences using English commas and periods

请先安装依赖,然后运行测试.

好：中文句子用全角标点

Good: Chinese sentences using full-width punctuation

请先安装依赖，然后运行测试。

坏：英文内容用了中文标点

Bad: English content using Chinese punctuation

Run

npm install

，then

npm test

。

Run

npm install

，then

npm test

。

好：英文内容用半角标点

Good: English content using half-width punctuation

Run

npm install

, then

npm test

.

undefined

Run

npm install

, then

npm test

.

undefined

问题五：缺乏结构化

Issue 5: Lack of Structure

undefined

undefined

坏：一大段文字没有分段

Bad: A large block of text without segmentation

本系统使用 Redis 做缓存提高查询性能同时使用 MySQL 做持久化存储数据写入时先写 MySQL 再异步更新 Redis 缓存读取时先查 Redis 如果未命中再查 MySQL 并将结果回写缓存设置过期时间为 30 分钟……

好：用列表和分段组织信息

Good: Organize information with lists and sections

本系统的缓存策略如下：

存储层： MySQL（持久化）+ Redis（缓存）
写入流程： 先写 MySQL，再异步更新 Redis
读取流程： 先查 Redis → 未命中则查 MySQL → 回写 Redis
缓存过期： TTL 设为 30 分钟

undefined

本系统的缓存策略如下：

存储层： MySQL（持久化）+ Redis（缓存）
写入流程： 先写 MySQL，再异步更新 Redis
读取流程： 先查 Redis → 未命中则查 MySQL → 回写 Redis
缓存过期： TTL 设为 30 分钟

undefined

写作检查清单

Writing Checklist

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

Before publishing the document, check each item:

排版

Formatting

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

Spaces between Chinese and English
Spaces between Chinese and numbers
Full-width punctuation used in Chinese context
Half-width punctuation used in English/code sections
No mixed full-width and half-width punctuation

术语

Terminology

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

Proper nouns retained in original English
Chinese-English annotations added for first-occurrence terms
No over-translation of industry-standard terms
Consistent terminology usage throughout

内容

Content

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

Short sentences, no Europeanized long sentences
No unnecessary passive voice
Structured information using lists and tables
Code examples are runnable
No machine translation vibe

格式

Format

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

Correct heading hierarchy (no skipping levels)
Code blocks labeled with language type
Links are accessible
Images have alt text

chinese-documentation

Original

Translation

中文技术文档写作规范

Chinese Technical Documentation Writing Guidelines

概述

Overview

中文排版规范

Chinese Formatting Standards

空格

Spaces

好

好

坏

坏

好

好

坏

坏

好

好

坏

坏

好

好

坏

坏

好

好

坏

坏

标点符号

Punctuation

好

好

坏

坏

好

好

坏

坏

中文语境用全角括号

Use full-width parentheses in Chinese context

括号内有英文或数字时用半角括号

Use half-width parentheses when containing English or numbers

纯英文内容用半角括号

Use half-width parentheses for pure English content

中文使用直角引号（推荐）

Use right-angle quotation marks for Chinese (recommended)

也可以使用弯引号（视团队规范而定）

Curved quotation marks are also acceptable (subject to team standards)

嵌套引号

Nested quotation marks

数字

Numbers

阿拉伯数字（技术文档中统一使用半角数字）

Arabic numerals (use half-width numerals uniformly in technical documentation)

不要用中文数字写技术参数

Do not use Chinese numerals for technical parameters

坏：支持最多一百个并发连接。

Bad: 支持最多一百个并发连接。

数字使用半角字符

Use half-width characters for numbers

中英混排最佳实践

Best Practices for Mixed Chinese-English Layout

术语处理原则

Terminology Handling Principles

首次出现标注翻译

Add Chinese-English annotations on first occurrence

好

好

后续出现直接使用

Use directly in subsequent occurrences

避免过度翻译

Avoid over-translation

好：保留业界通用英文术语

Good: Retain industry-standard English terms

坏：强行翻译反而看不懂

Bad: Forced translation makes it hard to understand

好