chinese-documentation

Chinese Technical Documentation Writing Standards

Overview

The most common problem in Chinese technical documentation is not insufficient content, but ratherawkward to read—Chinese and English crammed together without spaces, inconsistent use of full-width and half-width characters, and a strong translationese flavor. This skill provides a complete set of Chinese technical documentation writing standards to make your documentsprofessional, readable, and immersive。

Core principles: Layout serves the reading experience, standards serve consistency, and content serves the reader.

Reference standards: Chinese Copywriting Layout Guide

Chinese Typography Standards

Spaces

Add spaces between Chinese and English:

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

Bad

Use Git for version management, combined with Jenkins for continuous integration.


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

Good

This update includes 3 new features and 12 Bug fixes.

Bad

This update includes 3 new features and 12 Bug fixes.


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

Good

The file size must not exceed 5 MB, and the response time should be kept within 200 ms.

Bad

The file size must not exceed 5 MB, and the response time should be kept within 200 ms.


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

Good

Today's temperature is 32°C, and CPU usage is 95%.

Bad

Today's temperature is 32 °C, and CPU usage is 95 %.


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

Good

Please refer to the official documentation for more information.

Bad

Please refer tothe official documentationfor more information.


### 标点符号

**中文语境使用全角标点：**

Good

Note: This API requires authentication. Please obtain a Token first.

Bad

Note: This API requires authentication, please obtain a Token first.


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

Good

The project uses the MIT license. See the LICENSE file for details.

Bad

The project uses the MIT license , see the LICENSE file for details .


**括号的使用：**

Use full-width parentheses in Chinese contexts

Please run the installation command (see the instructions below).

Use half-width parentheses when the parentheses contain English or numbers

This project is developed based on Spring Boot (v3.2.0).

Use half-width parentheses for purely English content

See the documentation (README.md) for details.


**引号的使用：**

Use corner brackets for Chinese (recommended)

The 「OK」 button triggers form submission, and the 「Cancel」 button closes the popup.

Curly quotes may also be used (depending on team standards)

The "OK" button triggers form submission, and the "Cancel" button closes the popup.

Nested quotes

He said: "Please click the 『OK』 button."


### 数字

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

Supports up to 100 concurrent connections.

Do not write technical parameters in Chinese numerals Bad: Supports up to one hundred concurrent connections. Use half-width characters for numerals

Version number v2.1.0, port number 8080, HTTP status code 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 → 负载均衡
- 文档标题和章节名（尽量中文，技术名词可保留英文）

### 首次出现标注翻译

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

Good

This system uses a message queue to implement asynchronous communication, and uses a dead letter queue to handle messages that fail to be consumed.

Subsequent occurrences can directly use

Consumers of the message queue need to implement idempotency...


### 避免过度翻译

Good: retain common industry English terminology

Do parameter validation at the Controller layer, and handle business logic at the Service layer.

Bad: forced translation makes it harder to understand instead

Do parameter validation at the controller layer, and handle business logic at the service layer.

Good

Use Redis for Session caching.

Bad

Use "Remote Dictionary Service" for "session" caching.


## 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 或更换优惠券 |

Amount representation convention

# 好：明确说明单位
total_amount: 9900  // 单位：分（即 99.00 元）

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

README.md Chinese template

Common README structure used by domestic open-source projects:

# 项目名称

[![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

### 安装

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

### 基本用法

\```typescript
import { 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)

Common questions and pitfall-avoidance guide

Issue 1: Machine-translation flavor

Characteristics: Sentence structure is stiff and does not conform to Chinese expression habits.

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

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

Key points:

Avoid passive voice ("被用来" → "用于")
Avoid redundant pronouns ("你想要" → say it directly)
Avoid literal translation of English sentence patterns

Issue 2: Europeanized sentence structure

Characteristics: Long attributives, multiple clauses, and a sentence that cannot be finished in one breath.

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

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

Key points:

Split long sentences into short sentences
Change attributive clauses into coordinate clauses
Say only one thing per sentence

Issue 3: Over-translation

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

# 正常写法
请打开终端，运行 npm install。

Issue 4: Mixed use of Chinese and English punctuation

# 坏：中文句子用了英文逗号和句号
请先安装依赖,然后运行测试.

# 好：中文句子用全角标点
请先安装依赖，然后运行测试。

# 坏：英文内容用了中文标点
Run `npm install`，then `npm test`。

# 好：英文内容用半角标点
Run `npm install`, then `npm test`.

Issue 5: Lack of structure

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

# 好：用列表和分段组织信息
本系统的缓存策略如下：

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

Writing checklist

Before publishing documentation, check item by item:

Formatting

Spaces between Chinese and English
Spaces between Chinese and numbers
Use full-width punctuation in Chinese context
Use half-width punctuation in English/code parts
No mixed use of full-width and half-width punctuation

Terminology

Proper nouns retain the original English
Terms appearing for the first time are annotated with Chinese-English equivalents
No over-translation of common industry terms
Terminology is used consistently throughout

Content

Sentences are short, with no Europeanized long sentences
No unnecessary passive voice
Use lists and tables to organize structured information
Code examples can be run directly
No "machine-translation flavor"

Format

Heading levels are correct (no skipped levels)
Code blocks are marked with language type
Links can be accessed normally
Images have alt text

About this skill

Overview

Chinese Typography Standards

Spaces

Amount representation convention

README.md Chinese template

Common questions and pitfall-avoidance guide

Issue 1: Machine-translation flavor

Issue 2: Europeanized sentence structure

Issue 3: Over-translation

Issue 4: Mixed use of Chinese and English punctuation

Issue 5: Lack of structure

Writing checklist

Formatting

Terminology

Content

Format