chinese-documentation

1# 中文技术文档写作规范
2 
3## 概述
4 
5中文技术文档最常见的问题不是内容不够，而是**读起来别扭**——中英文挤在一起没有空格、全角半角混用、一股机翻味。本技能提供一套完整的中文技术文档写作规范，让你的文档**专业、好读、不出戏**。
6 
7**核心原则：** 排版服务于阅读体验，规范服务于一致性，内容服务于读者。
8 
9**参考标准：** [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)
10 
11## 中文排版规范
12 
13### 空格
14 
15**中英文之间加空格：**
16 
17```
18# 好
19使用 Git 进行版本管理，配合 Jenkins 实现持续集成。
20 
21# 坏
22使用Git进行版本管理，配合Jenkins实现持续集成。
23```
24 
25**中文与数字之间加空格：**
26 
27```
28# 好
29本次更新包含 3 个新功能和 12 个 Bug 修复。
30 
31# 坏
32本次更新包含3个新功能和12个Bug修复。
33```
34 
35**数字与单位之间加空格：**
36 
37```
38# 好
39文件大小不超过 5 MB，响应时间控制在 200 ms 以内。
40 
41# 坏
42文件大小不超过5MB，响应时间控制在200ms以内。
43```
44 
45**例外：度数、百分比等不加空格：**
46 
47```
48# 好
49今天气温 32°C，CPU 使用率 95%。
50 
51# 坏
52今天气温 32 °C，CPU 使用率 95 %。
53```
54 
55**链接前后加空格：**
56 
57```
58# 好
59请参考 [官方文档](https://example.com) 获取更多信息。
60 
61# 坏
62请参考[官方文档](https://example.com)获取更多信息。
63```
64 
65### 标点符号
66 
67**中文语境使用全角标点：**
68 
69```
70# 好
71注意：该接口需要鉴权，请先获取 Token。
72 
73# 坏
74注意:该接口需要鉴权,请先获取 Token.
75```
76 
77**全角标点与英文/数字之间不加空格：**
78 
79```
80# 好
81项目使用 MIT 协议，详见 LICENSE 文件。
82 
83# 坏
84项目使用 MIT 协议 ，详见 LICENSE 文件 。
85```
86 
87**括号的使用：**
88 
89```
90# 中文语境用全角括号
91请运行安装命令（详见下方说明）。
92 
93# 括号内有英文或数字时用半角括号
94该项目基于 Spring Boot (v3.2.0) 开发。
95 
96# 纯英文内容用半角括号
97See the documentation (README.md) for details.
98```
99 
100**引号的使用：**
101 
102```
103# 中文使用直角引号（推荐）
104「确定」按钮触发表单提交，「取消」按钮关闭弹窗。
105 
106# 也可以使用弯引号（视团队规范而定）
107"确定"按钮触发表单提交，"取消"按钮关闭弹窗。
108 
109# 嵌套引号
110他说：「请点击『确定』按钮。」
111```
112 
113### 数字
114 
115```
116# 阿拉伯数字（技术文档中统一使用半角数字）
117支持最多 100 个并发连接。
118 
119# 不要用中文数字写技术参数
120# 坏：支持最多一百个并发连接。
121 
122# 数字使用半角字符
123版本号 v2.1.0，端口号 8080，HTTP 状态码 200。
124```
125 
126## 中英混排最佳实践
127 
128### 术语处理原则
129 
130**保留英文的情况：**
131 
132- 专有名词：React、Kubernetes、Redis、MySQL
133- 行业通用缩写：API、SDK、CLI、ORM、CI/CD
134- 命令和代码：`npm install`、`git commit`
135…