# 中文技术文档写作指南
引言 本指南规范了一种面向技术领域的中文写作风格，主要用于技术文档的编写与维护。 素材来源于互联网公开资源，是各家中文文案风格指南的综合，结合实际项目经验提炼而成，旨在对中文技术文档在语言风格、结构样式、内容元素、标点符号、格式排版等方面给出可落地的参考规范。 希望本指南的发布，能为日后业界标准的建立和知识共享文化的推动贡献一份力量。 ...

2025年11月03日53分钟阅读

## 引言

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

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

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

### 目的

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

### 愿景

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

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

### 核心理念

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 中文排版需求

中文写作参考

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