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

Add spaces between Chinese and English:

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

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

Add spaces between Chinese and numbers:

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

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

Add spaces between numbers and units:

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

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

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

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

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

Add spaces around links:

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

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

Punctuation

Use full-width punctuation in Chinese context:

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

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

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

# 好
项目使用 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.

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
他说：「请点击『确定』按钮。」

Numbers

# 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。

Best Practices for Mixed Chinese-English Layout

Terminology Handling Principles

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

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

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

# Use directly in subsequent occurrences
消息队列的消费者需要实现幂等性……

Avoid over-translation

# Good: Retain industry-standard English terms
在 Controller 层做参数校验，Service 层处理业务逻辑。

# Bad: Forced translation makes it hard to understand
在控制器层做参数校验，服务层处理业务逻辑。

# Good
使用 Redis 做 Session 缓存。

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

Chinese-English Format for API Documentation

API Documentation Template

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

Convention for Amount Representation

# Good: Clearly specify the unit
total_amount: 9900  // 单位：分（即 99.00 元）

# Bad: No unit specified, causing ambiguity
total_amount: 99.00  // Is it yuan or cents? Floating-point numbers have precision issues

Chinese README.md Template

Common README structure for domestic open-source projects:

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

### 安装

\```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 Issues and Pitfall Avoidance Guide

Issue 1: Machine Translation Vibe

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

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

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

Key Points:

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

Issue 2: Europeanized Sentence Structure

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

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

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

Key Points:

Split long sentences into short ones
Convert attributive clauses to coordinate clauses
Focus on one idea per sentence

Issue 3: Over-translation

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

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

Issue 4: Mixed Chinese and English Punctuation

# 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`。

# Good: English content using half-width punctuation
Run `npm install`, then `npm test`.

Issue 5: Lack of Structure

# 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 分钟

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

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

chinese-documentation

NPX Install

Tags

SKILL.md Content (Chinese)