中文技术文档写作指南

引言

本指南规范了一种面向技术领域的中文写作风格，主要用于技术文档的编写与维护。

素材来源于互联网公开资源，是各家中文文案风格指南的综合，结合实际项目经验提炼而成，旨在对中文技术文档在语言风格、结构样式、内容元素、标点符号、格式排版等方面给出可落地的参考规范。

希望本指南的发布，能为日后业界标准的建立和知识共享文化的推动贡献一份力量。

目的

• 提高中文技术文档的清晰度、可读性与一致性。
• 统一文档风格，确保组织对外输出形象与质量的一致性。
• 降低不同文档作者对同一问题反复作出判断的时间成本。
• 提供一套可持续演进的写作和审校基线。

愿景

本指南不仅是一个工具手册，更是一份对高质量中文内容的价值承诺。我们希望所有文档都能体现以下特征：

• 真实准确
• 清晰简洁
• 结构合理
• 风格统一
• 易于维护

核心理念

1. 一致性优先：无论内容作者、项目背景或发布时间，文档都应遵循统一的语言风格和排版规范，避免风格漂移。
2. 最小惊讶原则：所有表达应符合预期，不制造理解歧义或认知负担。
3. 可维护性导向：内容、格式和结构都要便于后续修订、复用和版本管理。
4. 结构先于美观：优先保证逻辑结构清晰，再考虑排版视觉优化。
5. 演进与共建：规范不是静态文件，而是在实际使用中不断修订完善的活文档。

适用范围

本指南适用于：

• 中文技术文档的编写者（产品经理、研发人员、技术写作人员等）。
• 文档审校和发布过程的争议裁定。
• 软件界面、帮助文档、培训资料等其他内容的参考依据。

如与特定项目或产品规范冲突，应优先遵循项目自定义标准，并在此基础上参考本指南。

使用原则

本指南推荐使用方式：

1. 快速总览：初次阅读时，先大致浏览目录和章节，了解指南覆盖的核心内容和分类方法。
2. 按需检索：在实际编写或审校过程中，遇到具体问题再回头查找相应规范。
3. 持续反馈：在日常使用中，如有任何适配问题或改进建议，均可提交修订意见。

修订与审查

1. 定期修订：定期开展一次全局回顾，结合实践经验对内容进行更新，保持准确性与时效性。
2. 多人审查：所有重大变更应经过至少两人审校，确保多视角验证和质量共担。
3. 版本管理：所有修订应记录版本号、修订人、修订日期及简要说明，便于追溯和比对。

标点符号

标点符号规范的本质，是让技术文档在多语言和多平台环境中保持一致性、可读性与专业性。

在复杂的中英文混排、Markdown 渲染、代码示例引用等场景下，标点用法既关乎排版美观，更直接影响语义准确、解析兼容与用户体验。

常用中文标点符号

句号「。」

句号用于标示一句话的结束。在 Markdown 及其他文本标记语言中，句号的使用与常规一致。

本软件支持多种数据格式处理。

逗号「，」

逗号用于在句子中分隔成分或表示停顿。

我们支持，Windows，Linux，和 macOS 系统。❌

顿号「、」

顿号用于列举或枚举同类事物。

本文将介绍算法的设计、实现、测试和优化过程。

分号「；」

分号用于并列复句中，连接意义密切的分句。

数据处理模块负责数据清洗；可视化模块负责结果呈现。

冒号「：」

冒号用于引出解释、说明或下文的内容。

注意：请先安装依赖库，再执行后续命令。

引号「“ ”，‘ ’」

引号用于标明引用、特定术语或需强调的内容。

他强调：“在生产环境中务必关闭调试模式。”

括号「（）」

括号用于添加解释，注释，或者附加的信息。

请确保 Python（版本≥3.7）已正确安装。

书名号「《》」

书名号用于标示书籍、报刊、文档或作品的标题。

我正在阅读《Linux 内核设计与实现》。

连接号「-」

连接号（短横线）用于连接相关的词语或组成复合词。

中美贸易协定 (China-US Trade Agreement)

破折号「——」

破折号用于插入补充说明、转折或强调。

他对结果非常满意——尽管时间有限。

省略号「……」

省略号用于表示语意的省略或延续。

等待系统初始化……

感叹号「！」

感叹号用于表示强烈情感或命令。

操作成功！

斜杠「/」

在 Markdown 中，斜杠常用于路径表示，也可用于分隔选项。

路径示例：/usr/local/bin

反斜杠「\」

反斜杠用于转义特殊字符。

输入 \\ 可输出一个反斜杠符号。

反引号「`」

反引号用于标注行内代码。

print('Hello, World!') 将输出“Hello, World!”。

中文标点使用

在技术文档中，推荐遵循以下核心规则：

1. 全角优先原则： 中文语境下，标点应使用全角形式（中文输入法标点），避免半角（英文）标点。

   这是中文文本. ❌

   这是中文文本。

2. 空格规范： 中文全角标点前后不添加半角空格。

   如果 CPU 设有限额 （从 K8S 指定的上限） ，请调整。❌

   如果 CPU 设有限额（从 K8S 指定的上限），请调整。

3. 行首行尾禁忌：

   • 句号、逗号、顿号、问号、叹号、分号、冒号、结束引号及括号等不得出现在一行开头。
   • 开始引号、括号、书名号不得出现在一行末尾。

   错误示例：

   她对我们说：“

   这本书很精彩。” ❌

   正确示例：

   她对我们说：“这本书很精彩。”

中英文混用时的用法

在中文技术文档中频繁出现英文术语、短语或句子。需严格区分中英文标点混用规范。

根本原则

• 中文技术文档以中文标点为主，英文标点为辅。
• 若夹入英文短语，保留其内部原生标点，但整体使用中文句号、逗号等。

基本规范

场景一：中文句子内夹英文单词或短语

• 不使用引号包裹。
• 保留英文内部标点。
• 句尾使用中文标点。

正确示例：

这个参数名为 timeout，表示超时时间。

场景二：中文句子内夹完整英文句子

• 用中文引号包裹英文句子。
• 英文句子内标点保持原样。
• 中文句子末尾使用中文句号。

正确示例：

官方文档写道：“Try it out, and you will get a 10% discount.”。

对比表

标点符号	中文句子内英文短语	中文句子内英文句子
句号	变量名为 default_value。	她说：“I like open-source software.”。
逗号	可选参数包括 id、name、status。	他强调：“Use caution, or you may lose data.”。
问号	distributed SQL 在这里是什么意思？	他问：“Is this configuration correct?”？
感叹号	请勿使用 drop 命令！	她喊道：“Success!”。
顿号	常用的 be 动词有 is、are、was 等。	“He is man.”、“He is the man.”含义不同。

中英文括号规范

1. 括号内全英文： 使用半角括号，括号与两侧各空一个半角空格，括号内外无额外空格。

   数据定义语言（DDL）是一种…… ❌

数据定义语言 (DDL) 是一种……

1. 括号内含中文： 使用全角括号，不加空格。

   文件系统（file system）包含多种类型。

英文作品标题引用

• 书籍/报刊： 斜体（如支持）或中文引号。
• 文章标题： 中文引号。

正确示例：

《New York Times》发表了题为“Cloud is Eating the World”的文章。

或

New York Times 发表了“Cloud is Eating the World”一文。

命名规范

命名规范是技术文档体系的核心基石之一，其本质在于通过清晰、一致、可解析的名称，确保文档在多工具、多平台及多语言环境中具备高可识别性、可维护性与可扩展性。

在实践中，合理的命名不仅直接提升可读性和检索效率，还显著增强链接稳定性、SEO 表现和跨团队协作体验。

文件命名

在以 Markdown 等标记语言撰写的技术文档中，文件命名应遵循以下原则与规则：

1. 语义明确：文件名应简洁、直观地概述文件所承载的主要内容或主题。
2. 长度适中：文件名长度建议不超过 50 个字符，以避免在文件系统或 URL 中产生不必要的截断或显示异常。
3. 分隔符规范：多个英文单词组成的文件名，统一使用短横线（-）分隔，禁止使用下划线（_）。下划线在某些 URL 编码或 Markdown 实现中可能被识别为修饰符，影响搜索引擎收录及样式兼容性。
4. 大小写一致：文件名应统一使用全小写或全大写，避免混用大小写（例如：ReadMe.md 应规整为 README.md）。
5. 扩展名规范：文件扩展名统一采用小写形式，例如：.md。虽然 .markdown 亦可接受，但在同一项目或库中必须保持一致。

示例文件：

文件名	内容描述
introduction-to-python.md	Python 语言的入门教程
database-connection-guide.md	数据库连接配置与最佳实践
faq.md	项目的常见问题与解答
deployment-instructions.md	部署步骤及注意事项
README.md	项目总览及使用说明
troubleshooting-reference.md	故障排查手册
Introduction_to_Python.md	使用下划线分隔词语 ❌
Install Guide.MD	混用空格及扩展名大写 ❌
ReadMe.md	首字母大小写混用 ❌

产品命名

在技术文档、市场资料及用户界面中，产品和工具的命名应严格遵循一致性与准确性原则，兼顾法律合规与品牌形象。

1. 唯一性：命名需确保在组织内部和外部均无重名或歧义。
2. 语义直观：产品名称应准确反映其主要功能或定位。
3. 统一格式：对所有正式文档，须使用官方产品全称，避免缩写或非正式别称。
4. 命名流程：组织应设立产品命名审议流程，并维护官方产品名称登记表，确保跨团队一致性。

示例：

英文产品名称	中文产品名称
Microsoft Office	微软办公软件
Adobe Photoshop	阿多比 Photoshop
Kubernetes	Kubernetes
TensorFlow	TensorFlow

名称使用

在中文技术文档中，正确、统一地使用国外组织、品牌或产品名称，是维护专业性和读者理解的一项基本要求。

国外组织、品牌或产品名称使用规范

通用规则：

1. 当中文官方译名已被广泛接受且读者普遍熟悉时，应直接使用译名。

   我们的产品支持微软（Microsoft）Azure 云服务。

2. 当名称有官方译名但读者不熟悉时，首次出现使用「中文官方译名（英文官方名称）」格式；后续可仅用中文译名。

   本文引用了威睿（VMware）的虚拟化平台。

3. 当无官方译名时，直接使用英文名称，并保持正确的大小写。

   请参阅 GitHub 上的相关开源项目。

注意： 判断「读者熟悉程度」需结合受众定位。如有疑虑，优先采用「中文官方译名（英文官方名称）」格式。

组织、品牌或产品名称对照表

下表提供部分常用名称及对应规范用法：

中文读者熟知官方译名	中文官方译名（不常用）	无官方译名
微软 (Microsoft)	威睿 (VMware)	GitHub
苹果 (Apple)	塔多思 (Trados)	SDL
甲骨文 (Oracle)	雪佛龙 (Chevron)	MySQL
亚马逊 (Amazon)	大众 (Volkswagen)	MongoDB
惠普 (HP)	戴姆勒 (Daimler)	Azure
宝马 (BMW)	西门子 (Siemens)	Jira
波音 (Boeing)	软银 (SoftBank)	Slack
雀巢 (Nestle)	东芝 (Toshiba)	Docker
宝洁 (Procter & Gamble)	思科 (Cisco)	Kubernetes
强生 (Johnson & Johnson)	瑞声 (Resound)	Ansible
索尼 (Sony)	罗克韦尔 (Rockwell Automation)	GitLab
百事 (Pepsi)	三洋 (Sanyo)	TensorFlow
可口可乐 (Coca-Cola)	格雷普 (Crepe)	Elasticsearch
高盛 (Goldman Sachs)	微步 (Microstep)	PyTorch
佳能 (Canon)	三菱 (Mitsubishi)	Apache Kafka
推特 (Twitter)	亚都 (Audu)	Redis
脸书 (Facebook)	逸碧 (Epyc)	Apache Spark
领英 (LinkedIn)	萨博 (Saab)	Terraform

一致性保障措施

为避免术语混乱和命名漂移，建议采取以下一致性保障措施：

1. 版本控制： 所有命名表应纳入版本库进行跟踪。对命名标准的调整需经审批并记录变更日志。
2. 命名白名单： 建立「官方命名白名单」，在写作、翻译及审校中强制对照。
3. 自动校验： 利用 lint 工具或正则规则对文档进行命名一致性检查。
4. 协作约定： 团队内部保持命名惯例培训与共享，确保新成员快速熟悉。

风格语气

技术文档的风格与语气，直接影响读者对内容的理解、信任与使用效率。其本质是以清晰、专业、友好的方式传递技术信息，使不同背景的用户均能准确理解并应用。

对话式语气

技术文档应避免冷漠、官僚化的表达，推荐采用平易近人、直截了当的语气，拉近与用户的距离。

在可能的场合，使用第二人称（如“你可以”），让读者感受到直接的指导和鼓励。

错误示例：

请使用下面的按钮来完成操作。❌

改进示例：

你可以使用下面的按钮来完成操作。

推荐实践：

• 尽量避免被动语态。
• 避免模糊表达（如“可以考虑”“或许可以”）。

客观礼貌的语气

技术文档应保持中立、客观、礼貌的基调，不夹带情绪、推销或指责色彩，确保读者能专注于技术本身。

语气应冷静、专业，避免强迫性表达。

错误示例：

你一定要按照这样做，否则会失败。❌

改进示例：

建议按照以下步骤操作，以确保流程顺利完成。

推荐实践：

• 使用“建议”“推荐”等中性词。
• 避免情绪化词汇，如“必须”“绝对不能”。

简洁清晰地表达

简洁性是高质量技术文档的基本特征。

建议作者在初稿完成后，逐句检查冗余字词，删除无意义的修饰语和重复内容。尽可能使用主动语态、短句、并列结构。

错误示例：

如果在配置过程中出现问题，那么需要查看日志文件，然后分析日志文件中的错误信息，最后采取适当的措施来解决问题。❌

改进示例：

配置过程中出现问题时，查看日志文件，分析错误信息，并采取相应措施解决。

推荐实践：

• 一句话不超过 25～30 个汉字。
• 一个段落聚焦一个主题。
• 避免无谓的过渡词（如“在此情况下”）。

通俗易懂的语词

技术文档应使用标准术语与通俗表达相结合的方式，确保准确性与易理解性。

应当避免：

• 行话、俚语。
• 网络流行语。
• 谐音或刻意错别字。

错误示例：

这个软件有魔改功能，能让你的计算机跑得飞快！❌

改进示例：

该软件具备优化功能，可以显著提升计算机的运行速度。

推荐实践：

• 如需引入专业术语，应提供简要解释。
• 避免缩略语泛滥，首次出现需给出全称。

以用户为导向

以用户为中心是技术文档写作的根本。写作者需在内容中充分考虑：

• 目标读者的知识水平。
• 实际操作流程和潜在问题。

建议定期进行可用性测试，邀请不同背景用户试用文档并反馈。

错误示例：

在设置菜单中，选择适当的选项以进行配置。❌

改进示例：

在设置菜单中，依次选择“系统设置” > “网络配置”，完成相关参数设置。

推荐实践：

• 提供操作路径、截图或示例。
• 针对常见问题提供明确的解决方案链接。

用词恰当和统一

统一性是技术文档可信度的重要保障。 所有同一产品或功能的名称、术语应全篇保持一致。 避免：

• 不必要的情绪用词。
• 同义词混用（如“建议/推荐/强烈推荐”不分）。

错误示例：

我们强烈推荐使用最新版本的软件。❌

改进示例：

建议使用最新版本的软件。

推荐实践：

• 制定术语表和术语白名单。
• 定期进行术语审校。

正确使用“的”、“地”、“得”

在中文技术文档中，“的”、“地”、“得”用法错误十分常见，需重点注意：

• “的”： 形容词 + 的 + 名词
• “地”： 副词 + 地 + 动词
• “得”： 动词 + 得 + 副词

正确示例：

调度系统会将数据迁移到其他的存储节点上。（形容词 + 的 + 名词）

数据库可以显式地使用事务。（副词 + 地 + 动词）

这个值不宜调得过大。（动词 + 得 + 副词）

推荐实践：

• 写作完成后，重点校对“的、地、得”。
• 对不确定用法，可拆分句子判断词性。

明确代词指代

代词指代必须清晰明确，避免歧义。

尤其在列举多项对象时，**“其”“它”“他们”**等代词需谨慎使用。

错误示例：

如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将其 image 字段留空。❌

改进示例：

如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将相应镜像的 image 字段留空。

推荐实践：

• 如有多项对象，尽量重复具体名词。
• 长句中慎用“其”“其余”等代词。

校对流程

为保障风格语气的一致性与高质量，建议在技术文档写作中遵循以下流程：

1. 初稿撰写： 聚焦核心信息，不拘泥语气。
2. 第一轮修订： 调整为对话式、客观、简洁语气，删除冗余表达。
3. 术语统一： 全文检索术语、代词，统一表述。
4. 校对检查： 重点核对“的、地、得”用法，确认代词指代清晰。
5. 可用性验证： 邀请目标读者试用文档并反馈。

文档内容

空白符、列表、表格、图像、代码块、链接、数字、拼写和语法规范等细节，是技术文档可读性、专业性与可维护性的核心保障。

良好的格式与排版不仅提升内容的清晰度与可理解性，还能显著降低歧义、增强检索效率、促进跨团队协作。

空白符号

空白符包括空格与空行，用于划分逻辑结构和增强排版美感。

空格

• 使用半角空格，禁止使用全角空格。
• 在中文与英文、阿拉伯数字之间，使用半角空格进行分隔。
• 除缩进、列表级别、代码块及 Markdown 表格外，禁止连续出现多个空格。
• 禁止使用 Tab 键替代空格。

错误示例：

这是一段□□□文本。❌

正确示例：

这是一段文本，包含中文、English words 和 12345。

空行

• 段落之间、不同排版格式之间，必须用一个空行隔开。
• 推荐使用空格缩进，不允许使用 Tab 键。
• 禁止连续出现两个及以上空行。

正确示例：

# 这是一个标题
 
这是第一段。
 
这是第二段。

错误示例：

这是一段文本。
 
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
 
这是另一段错误的文本。❌

列表

列表用于分项呈现信息，明确逻辑结构。

• 使用无序列表表示多项并列信息。

• 使用有序列表表示需按顺序执行的步骤。

• 列表项尽量使用相同的语法结构，保持标点一致。

• 列表层级不超过三级嵌套。

无序列表

以下是需关注的事项：
- 项目预算
- 团队规模
- 项目时间线
- 预期成果

有序列表

请按照以下步骤操作：
1. 打开电脑。
2. 启动浏览器。
3. 输入网址并访问。

嵌套列表

产品包括以下部分：
- 外壳
  - 上盖
  - 下盖
- 内部组件
  - CPU
  - 内存

表格

表格用于对比、分组或组织结构化数据。

• 所有内容左对齐。

• 内容简明，避免大段文字。

• 表头一致性：同一类型表格的表头必须统一。

• 表格下方必须保留一行空行。

正确示例：

| 姓名   | 年龄 | 职业   |
|:------|:----|:------|
| 张三   | 25  | 程序员 |
| 李四   | 30  | 设计师 |
 
这是正文部分。

图形和图片

规范的图像使用能增强可视化表达，提升可用性。

• 图像必须清晰、可辨。

• 中文文档内的图片文字应使用中文，如含英文需先本地化。

• 建议使用免费、开源、可商用字体（如思源黑体）。

• 同一文档中字体应统一。

• 避免在图像中放置长段文字，可通过编号结合正文说明。

• 图中含有缩略语，需在图注中提供解释。

• 图片命名应具有描述性。

• 图片需添加替代文本（alt），以提高无障碍可访问性。

正确示例：

![示例图片：展示界面布局](/path/to/image.jpg "界面布局示例")
 
- **说明**：图1 展示了软件界面布局。图中文字使用思源黑体。缩略语 XYZ 表示“示例功能”。

代码块与注释

代码块与注释是技术文档核心要素，需保持清晰一致。

• 必须声明代码语言。

• 命令行示例需按逻辑换行，使用 \ 标明换行。

• 命令中涉及替换的参数，使用 < > 并提供注释。

• 除必要演示，代码中禁止包含错误或警告。

• 注释应简洁明了、准确无误，并统一使用英文。

代码块

```python
# Print greeting
print("Hello, World!")
```

长命令换行

```bash
command --option1 --option2 \
--option3 --option4
```

参数替换

```bash
ssh <username>@example.com
```

链接和引用

链接与引用必须精确、描述清晰、可长期访问。

• 链接应指向具体位置，如 GitHub 行号。
• 链接更新后需及时调整。
• 链接文本应准确描述内容，避免“这里”“此处”等模糊词。
• 引用应声明来源，不得使用相对路径。
• 推荐使用永久链接。

正确示例：

请参考 [Python 官方教程](https://docs.python.org/3/tutorial/index.html)。
 
阅读这篇 [文章](https://example.com/article) 以了解更多。
 
查看 [具体代码行](https://github.com/user/repo/blob/main/file.py#L42)。

缩略语

缩略语需在首处说明全称并解释。

汉语缩略语

• 使用时需保证语境清晰。
• 如非常用缩略语，首次出现时需给出全称。

本文使用“绑核”指代“核心绑定”。

英语缩略语

分类：

• 首字母缩略词（读作一个单词）：NATO
• 字母词（逐字母读）：FBI
• 缩写词（直接缩短）：App

规范：

• 标题：避免解释缩略语。
• 正文首次出现：提供全称和中文释义。
• 后续出现：直接使用缩略语。

人工智能（Artificial Intelligence，AI）正迅速发展。

数字

技术文档往往需要在中文语境下严谨地处理数字和拼写问题，以确保内容准确、一致、清晰，避免因表达混乱而产生理解歧义或数据误读。

在中文文档中，数字有汉字数字与阿拉伯数字两种表现形式。应根据场景、用途和表达意图合理选用。

汉字数字

汉字数字常用于表示概数、传统纪年、含数字的固定用语，或为突出庄重典雅的效果。

主要规范：

• 概数表达： 数字连用表示概数时，不使用顿号隔开。

  三四个月、一二十个

• 年份书写： 年份不可简写为两位数字。

  二三（错误）❌

• 月日专名： 含月日的专名使用间隔号「·」，并在前后加引号以避免歧义。

  “六·二六”事件

• 法律文书与财务票据： 使用大写汉字数字。

  肆仟贰佰叁拾肆元整

• “零”与“〇”区分：「零」：用于计量，「〇」：用于编号。

  十零个苹果

编号〇一〇二

常用场景及示例：

适用场景	示例
数字连用表示概数	三四十人、五六百套、一二十年
干支纪年和农历日期	丙寅年十月十五日、腊月二十三
固定用语和历史事件	四书五经、五四运动、“一·二八”事变
庄重典雅表达	十一届全国人大一次会议（不写为“11 届全国人大 1 次会议”）

阿拉伯数字

阿拉伯数字主要用于计量、编号、现代事物及突出简洁醒目的效果。

主要规范：

1. 形式： 使用半角数字、避免全角数字。

   2023

2. 分节符： 数字每三位使用半角逗号分隔。

   1,000,000

3. 范围表达： 使用浪纹式连接号「～」或一字线连接号「—」。

   10～20 或 10—20

4. 日期和时间： 年月日顺序：2023 年 6 月 26 日，时间：15:30:00。

5. 月日专名： 使用间隔号。

   “6·26”事件

常用场景及示例：

适用场景	示例
数学运算数字	-126、34.05%、1/500
计量单位数字	524.5 km、53 MB、12 h
编号	ISBN 978-7-80184-224-4、国办发 [1987]9 号、京 A00001
现代事物命名	4G 手机、MP4 播放器、维生素 B12、“5·27”事件
醒目表达	北京时间 2020 年 10 月 1 日 12 点整

单位符号

在涉及计量单位时，需注意格式、空格及符号规范。

主要规范：

1. 汉字名称： 推荐使用中文单位名称。

   三米（不写为 3m）

2. 空格间隔： 数值与单位之间通常空一个半角空格。

   3 kg

3. 特殊符号： 百分号、摄氏度、角度等符号与数值之间不空格。

   45°、20°C、50%

4. 英尺英寸符号： 与数字之间不空格。

   6’2”

单位形式示例表：

类型	示例
汉字单位	三米
间隔空格	3 kg
角度/温度/百分比	45°、20°C、50%
英尺/英寸	6’2”

拼写

技术文档既包含中文，又包含英文，拼写必须准确、一致，避免错别字及大小写混用。

中文拼写

1. 禁止简繁混用：

   这款软件的颜色设计很独特，它的界面顏色由用户选择。❌

   这款软件的颜色设计很独特，它的界面颜色由用户选择。

2. 禁止错别字：

   这款软件使用 MySOL 数据库存储数据。❌

   这款软件使用 MySQL 数据库存储数据。

英文拼写

英文拼写应保持大小写正确，一致性明确。

主要规范：

1. 英文专有名词保持首字母大写：

   用户可以在 mysql 数据库中创建新的表。❌

   用户可以在 MySQL 数据库中创建新的表。

2. 英文普通词汇小写： 当英文词出现在中文句中，非专有名词需小写。

   你可以使用 “SELECT” 语句获取数据。❌

   你可以使用 “select” 语句获取数据。

3. 完整英文句子保留首字母大写：

   请参阅 “in this chapter, we will learn how to create tables.”❌

   请参阅 “In this chapter, we will learn how to create tables.”

拼写一致性实践：

• 维护术语与拼写白名单。
• 编写统一的校对清单。
• 使用拼写检查工具（如 Grammarly、Spell Right）。

语法

成分残缺

成分残缺是指句子缺少必要的主语、谓语、宾语或定语，导致语义不完整。

在技术文档中，成分残缺不仅破坏句子结构，还会引起理解偏差。

错误示例

会话保持：在应用程序没有提供会话保持的功能下，HAProxy 可以提供该项功能。❌

改进示例：

会话保持：在应用程序没有提供会话保持功能的情况下，HAProxy 可以提供该项功能。

推荐实践：

• 写作后逐句检查主谓宾是否齐全。
• 确保条件状语从句及修饰语结构完整。

搭配不当

词语搭配不当是指词汇搭配错误或逻辑混乱，造成表达生硬或含糊。

错误示例：

HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，并仍然负责该项目的维护，该在开源社区提供免费和版本迭代。❌

改进示例：

HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，他现在仍然负责该项目的维护，并在开源社区免费提供版本迭代。

推荐实践：

• 熟悉常用技术搭配（如“提供服务”“发布版本”）。
• 尽量避免在一个句子中叠加过多修饰。

倍数表达

倍数表达是技术文档中常见的定量描述，需准确区分**“增加了”与“增加到”**，避免歧义或语法错误。

核心规范：

• “增加了”表示在原有基础上增加了多少。
• “增加到”表示总量达到了多少。
• 不使用“降低 N 倍”或“减少 N 倍”，而应改为“降低百分之几”或“减少百分之几”。

表达方式	示例	是否规范
增加了	处理速度增加了两倍。	✔
只用增加	处理速度增加两倍。	❌
增加到	处理速度增加到两倍。	✔
只用增加	处理速度增加两倍。	❌
降低了	处理速度降低了百分之五十。	✔
降低 N 倍	处理速度降低两倍。	❌

推荐实践：

• 表述时先确定参考值（基准）。
• 不用“翻倍”模糊表达。
• 尽量配合百分比说明，提升准确性。

成分多余

成分多余是指句中出现不必要或重复的信息，使表达臃肿，降低可读性。

错误示例：

根据官方建议，目前稳定版本的 HAProxy 为稳定版 2.0 特性。❌

改进示例：

官方建议使用 HAProxy 稳定版本 2.0。

推荐实践：

• 删除无意义的套话（如“根据建议”“目前为止”）。
• 同义修饰只保留一次（如“当前稳定版本”或“最新稳定版本”，择一）。

句式杂糅

句式杂糅是指在一个句子中混合使用多种句式结构，导致逻辑混乱或难以阅读。

错误示例：

当部署多个 DM-master 节点时，所有 DM-master 节点将使用内部嵌入的 etcd 组成集群并用于存储集群节点信息、任务配置等元数据，同时通过 etcd 选举出 leader 节点用于提供集群管理、数据迁移任务管理相关的各类服务。因此，若 DM-master 可用节点数超过部署节点的半数，即可正常提供服务。❌

改进示例：

当部署多个 DM-master 节点时，所有节点将使用内部嵌入的 etcd 组成集群。该集群用于存储节点信息、任务配置等元数据，并通过 etcd 选举 leader 节点。leader 节点提供集群管理和数据迁移任务管理服务。因此，若可用的 DM-master 节点数超过总数的一半，集群即可正常工作。

推荐实践：

• 超过 30 个字的句子，优先拆分。
• 每个句子只包含一个核心观点。
• 复杂并列关系，使用分号或多句分段。

校对流程

为确保语法规范和表述一致，建议采用以下写作与校对流程：

1. 第一轮审稿： 逐句检查成分完整性，确认搭配恰当。
2. 第二轮审稿： 重点审查倍数表达、数量范围用法。
3. 第三轮审稿： 删除多余成分，拆分杂糅句式。

文档结构

标题、段落和目录，是技术文档结构化表达的核心要素。

良好的标题层级和清晰的段落逻辑，不仅能帮助读者快速理解文档脉络，也能提升检索效率和跨平台渲染的可用性。

标题

层级规范

标题层级应递增使用，避免跳级。

常用的技术文档标题层级不超过三级，如需进一步分级，推荐改用列表、编号或分组说明代替四级标题。

正确示例：

# 文章主标题
## 一级章节标题
### 二级章节标题

错误示例：

#### 四级标题

如确有需要，可用列表或分组引导：

### 功能配置
- 子功能1：功能说明
- 子功能2：功能说明

推荐实践：

• 禁止跳级：二级标题下不能直接出现四级标题。
• 同一文档标题层级应保持一致性。

标题表述

标题应简洁、明确，并概括章节核心内容。

标题结构类型	示例
名词词组	数据结构、网络安全
主题词 + 动词	电池充电、程序执行
动词 + 主题词	安装软件、编写代码
定语 + 主题词	高效的算法、重要的更新
介词 + 定语 + 主题词	对数据结构的理解、在网络安全中的防御

注意事项：

1. 避免标题重复：若一级标题为“数据结构”，二级标题应进一步细化，如“数组”、“链表”，而非重复“数据结构”。
2. 避免使用标点：标题不使用句号、问号、感叹号等。
3. 避免在标题中解释缩略语：缩略语应在正文首次出现时进行解释。
4. 添加引导性句子：在相邻标题之间，可增加简短过渡语句。
5. 避免孤立标题：如果某部分仅有一个三级标题，建议提升为二级标题。
6. 列表最小单位：项目列表内不嵌套任何标题。列表中每一项应是完整的内容单元。

段落

段落是技术文档的基本构成单元，应具备明确主题、清晰逻辑、合理长度。

1. 主题句：每个段落应有一个主题句，通常位于开头。
2. 长度：建议每段 50~250 字，避免超过 300 字。
3. 句子简洁：每句建议不超过 100 字，优先使用简单句、并列句，复杂信息分拆为多句。
4. 先图表后文字：技术描述宜优先图表、流程图，再用文字解释。

段落示例：

1. 数据结构简介
 
数据结构是计算机科学中的核心概念（主题句）。它指数据值、数据间关系及操作方法的有序组织。合理选择数据结构将直接影响程序性能和可维护性（约50字）。
 
2. 数组和链表
 
数组和链表是最常见的数据结构（主题句）。如图1所示，数组是一种线性结构，包含一系列有序元素，每个元素有索引。链表由节点组成，每个节点包含一个值和指向下一个节点的指针（约60字）。

句式示例：

数据结构是计算机科学中的核心概念。（简单句）
 
数据结构直接影响程序性能，因此合理选择数据结构非常重要。（并列句）
 
数组包含有序元素，每个元素有索引；链表由节点组成，每个节点包含值和指针。（并列分句，避免过长）

目录

目录是帮助读者快速定位和浏览的重要工具。

应根据文档结构自动生成，包含所有章节、附录及必要索引。

推荐实践：

1. 技术手册：
   • 必须提供总目录，列出全部章节。
   • 若在网页端发布，应具备：
     • 全手册导航栏（总目录）
     • 页内导航栏（单篇目录）
2. 层级规范：确保目录与标题层级完全一致。在文档构建工具（如 Sphinx、MkDocs、Docusaurus）中配置正确的深度。
3. 动态更新：目录应随内容修改自动更新。

参考文献

在系统化编写与发布技术文档时，参考文献既是内容准确性与客观性的重要依据，也是支撑知识可信性、可追溯性与版权合规的核心要素。

高质量的技术文档必须在文末统一列出所有引用与参考资料，以便读者核实信息来源，满足版权合规要求，提升内容权威性。

范围

建议参考文献应涵盖以下类别资料：

1. 标准规范：各类国际标准、国家标准、行业标准（如 ISO、RFC、GB/T）。
2. 官方文档：项目或软件官方网站及权威文档库。
3. 白皮书与指南：官方发布的架构白皮书、最佳实践指南。
4. 技术论文：学术研究、技术研究论文。
5. 社区资料：经充分验证的开源社区资料（需注明版本）。
6. 书籍与出版物：专业出版社出版的技术著作。

格式

推荐采用一致的引用格式，可根据所在组织或项目选用以下标准之一：

• GB/T 7714—2015（中国国家标准）
• APA（美国心理学会格式，常用于教育研究）
• IEEE（国际电气电子工程师学会格式）
• Chicago（芝加哥手册）

在工程和技术文档中，常用简化版的统一编号格式，并明确标出：

• 作者（如有）
• 文档或页面标题
• 来源或出版单位
• URL
• 访问日期（强烈建议保留）

规范化示例

参考文献 [1] Kubernetes Authors. Kubernetes Documentation. Kubernetes.io. Available: https://kubernetes.io/docs/ [Accessed: 2024-03-01]. [2] Free Software Foundation. GNU Free Documentation License, Version 1.3. Available: https://www.gnu.org/licenses/fdl-1.3.html [Accessed: 2024-03-01]. [3] The OpenAPI Initiative. OpenAPI Specification. Swagger.io. Available: https://swagger.io/specification/ [Accessed: 2024-03-01]. [4] ISO/IEC. ISO/IEC 9126: Software Engineering—Product Quality. International Organization for Standardization, 2001. [5] Martin Fowler. Patterns of Enterprise Application Architecture. Addison-Wesley Professional, 2002. ISBN: 978-0321127426.

附录资料

高质量的技术文档应始终包含完善的附录内容，确保读者能够澄清概念、核实出处、识别法律边界。

术语表

术语表用于对关键概念进行定义、解释和范围界定，避免因理解偏差导致使用风险。

术语	定义
节点（Node）	在分布式系统中，节点是一个独立的实例，通常指运行某个服务的服务器或容器。
主节点（Master）	管理集群的元数据、负责任务调度的中心节点。
副本（Replica）	某个数据集或服务的冗余拷贝，用于高可用或负载均衡。

缩略语表

缩略语表应列出文档中出现的所有英文缩略词，提供全称、中文解释，方便读者快速查阅。

缩略语	英文全称	中文释义
API	Application Programming Interface	应用程序编程接口
SLA	Service Level Agreement	服务级别协议
DB	Database	数据库
CI	Continuous Integration	持续集成
CDN	Content Delivery Network	内容分发网络

推荐实践：

• 术语表和缩略语表应与版本管理同步更新。
• 如跨多项目共享，应维护统一术语库。
• 在文档首次出现术语时，建议以「全称（缩略语）」形式出现。

侵权与商标说明

技术文档涉及第三方产品、商标和资料时，需在显著位置（如首页底部、附录、版权页）提供侵权与商标声明，以降低法律争议风险。

建议声明内容包含：

1. 版权归属声明：明确文档版权归属及授权范围。

   本文档版权归属©2024 XX 公司，保留所有权利。未经授权，不得以任何形式复制或传播。

2. 商标使用说明：声明所引用商标、品牌归属权。

   文中提及的所有商标或注册商标均属于其各自所有者。

3. 免责声明：声明文档信息的适用性及责任范围。

   本文档仅供参考，XX 公司不对因使用本文档而导致的任何损失承担责任。

4. 引用来源说明：列明所有引用资料的出处和链接。

---

《中文技术文档写作指南》参考文献及资料

写作规范与风格指南

• Google Developer Documentation Style Guide
• Microsoft Docs 参与者指南概述
• LeanCloud 文案风格指南
• 豌豆荚文案风格指南
• Lengoo 简体中文规范指南
• 知乎专栏 - 写给大家看的中文排版指南
• Markdown 书写风格指南
• 中文文案排版指北

本地示范规范

• PingCAP Markdown 编码规范
• 中文技术文档的写作规范 (阮一峰)

语言文字标准

• 《常见语言文字错误防范手册》. 周奇主编. 北京: 中国标准出版社, 2010.

数字标准

• 《出版物上数字用法》GB/T 15835—2011
• 《出版物上数字用法的规定》GB/T 15835—1995

标点符号

• 《标点符号用法》GB/T 15834—2011
• 夹用英文的中文文本的标点符号用法（草案）
• 易混标点符号：一字线（—）、短横线（-）、浪纹线（～）

列表与排版

• 写给初学者的 Markdown 教程
• 英语技术文档中如何正确使用无序列表和有序列表？
• 使用无序列表的 7 项注意

「」引号使用

• 知乎：为什么在引用时，用直角引号（「」）而不是弯引号（“”）？

、顿号使用

• 8 例顿号误用解析 - 中国编辑校对网
• 顿号（标点符号）- 百度百科

空格与 Tab

• 缩进与对齐——正确地使用Tab和空格
• 使用tab还是空格？ - 知乎
• 缩进习惯对代码质量的影响

排版规范

• Requirements for Chinese Text Layout 中文排版需求

中文写作参考

• 余光中：怎样改进英式中文？——论中文的常态与变态