文档即产品！工程师必看的写作密码.md

在撰写技术文章、文档、博客或项目说明时，遵循一定的写作规范可以提升内容的专业性、可读性和实用性。

一、文章结构与逻辑

标题清晰
- 标题应简洁明确，反映核心内容（如《如何用 Python 实现快速排序》）。
- 避免模糊标题（如《一个有趣的问题》）。
- 分级标题层级明确（例如：# 一级标题 → ## 二级标题 → ### 三级标题）。
摘要/引言
- 开篇简要说明文章目标、解决的问题或适用场景。
  本文档旨在记录一些在实际开发工作中用到的实用且高效的 Git 命令和技巧，帮助大家更加高效地使用 Git 进行版本控制。
正文逻辑
- 分点说明：复杂问题拆解为步骤或模块（如使用 1. 2. 3. 或 - 列表）。
- 因果关系：先描述问题，再解释解决方案。
- 代码先行，解释在后：先展示代码片段，再详细说明其原理或注意事项。

二、内容规范

代码相关规范
- 代码块格式：
  - 使用代码高亮（如 Markdown 的 javascript 或 bash）。
  - 代码缩进、命名需符合语言规范。
- 代码注释：
  - 关键逻辑需添加注释（避免过度注释）。
```
// 这是一个简单的加法运算
const a = 1
const b = 2
const c = a + b
```
- 代码安全性：
  - 避免直接暴露敏感信息（如 API 密钥、密码）。
  - 伪代码或占位符示例：API_KEY = "<your-api-key>"。
术语与表述
- 术语准确：区分相似概念（如“进程 vs 线程”、“HTTP 1.1 vs HTTP/2”）。
- 避免口语化：用“函数”代替“方法”（若语言无关），用“调用”代替“跑一下”。
- 一致性：同一术语全文统一（如“服务器”或“服务端”二选一）。
技术细节处理
- 版本标注：明确技术依赖的版本（如“Node.js v18+”、“Python 3.9”）。
- 环境说明：标注操作系统、工具链等（如“测试环境：Ubuntu 22.04, Docker 24.0.5”）。
- 错误处理：提供常见报错及解决方案（如“若出现 ImportError，请检查依赖安装路径”）。

三、格式与排版

1. 标题

标题结构应注意保持简洁、逻辑清晰、格式统一，确保标题层级合理、内容明确、样式一致，提升文档专业性和可读性。

层级
标题层级建议使用四级结构。

# 文章总标题（一级标题）

## 主要部分的大标题（二级标题）

### 二级标题下的子标题（三级标题）

#### 三级标题下的细分标题（四级标题）

使用原则
- 层级禁止跳跃
  一级标题下不能直接出现三级标题。
```
// 错误示范

# 一级标题

### 三级标题
```
- 避免孤立标题
  同级标题需成组出现，避免单个标题孤立
```
// 错误示范: 二级标题 A 只包含一个三级标题，完全可以省略三级标题 A。

## 二级标题 A

### 三级标题 A

## 二级标题 B
```
- 禁止语义重复
  下级标题不能重复上级标题名称。
```
// 错误示范

## 概述

### 概述
```
- 慎用四级标题
  三级标题下建议使用项目列表，避免过多层级
```
// 推荐结构

### 三级标题

- A
- B
- C
```

2. 文本

文本内容应注意排版统一、语言简洁、风格正式、行文规范，确保文本格式一致、表达清晰、用语严谨、翻译标准。

字间距规则
- 中英文之间：
  全角中文与半角英文之间需加半角空格。
  示例： 启动 Windows 系统
- 中文与数字：
  全角中文与半角数字之间空格可选，但需统一风格。
  示例： 2025 年 2 月 26 日 或 2025年2月26日
- 单位与数字：
  英文单位与数字之间需留空格。
  示例： 16 GB
- 标点符号：
  半角英文、数字与全角标点之间不留空格。
  示例： MacBook Air。

句子写作原则

控制长度：

不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量不超过 20 字，长句不超过 40 字，避免复杂结构。

错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。
正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。

句式选择：

优先使用简单句和并列句，避免复合句。

并列句：他昨天生病了，没有参加会议。
复合句：那个昨天生病的人没有参加会议。

肯定表达：

尽量使用肯定句，避免否定句表达。

错误：请确认没有接通装置的电源。
正确：请确认装置的电源已关闭。

主动语态：

避免使用双重否定句，优先使用主动语态，避免被动语态。

错误：没有删除权限的用户，不能删除此文件。
正确：用户必须拥有删除权限，才能删除此文件。

写作风格

正式语言：

避免非正式表达，使用现代汉语常用词汇。

错误：这是唯二的快速启动的方法！！！
正确：这是仅有的两种快速启动的方法。

“的、地、得”：

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

她露出了开心的笑容。（形容词＋的＋名词）
她开心地笑了。（副词＋地＋动词）
她笑得很开心。（动词＋得＋副词）

代词明确：

使用代词时需明确指代对象。

错误：从管理系统可以监视中继系统和受其直接控制的分配系统。
正确：从管理系统可以监视两个系统：中继系统和受中继系统直接控制的分配系统。

形容词节制：

避免在名词前堆砌过多形容词。

错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。
正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。

英文处理规范

复数转单数：
英文复数形式翻译为中文时还原为单数

英文：...information stored in random access memory (RAMs)...
中文：⋯⋯ 存储在随机存取存储器（RAM）里的信息 ⋯⋯

缩写格式：
外文缩写使用半角圆点。
示例： U.S.A.
省略号：
表示中文时，英文省略号（...）改为中文省略号（⋯⋯）。
```
英文：5 minutes later...
中文：5 分钟过去了⋯⋯
```

书名号：

英文书名或电影名翻译为中文时，双引号应改为书名号。

英文：He published an article entitled "The Future of the Aviation".
中文：他发表了一篇名为《航空业的未来》的文章。

标注和缩写：
第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。
```
IOC（International Olympic Committee，国际奥林匹克委员会）。这样定义后，便可以直接使用“IOC”了。
```

专有名词：

专有名词首字母大写，非专有名词不需大写。

“American Association of Physicists in Medicine”（美国医学物理学家协会）是专有名词，需要大写。
“online transaction processing”（在线事务处理）不是专有名词，不应大写。

3. 段落

原则
- 一个段落只能有一个主题，或一个中心句子。
- 段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为中心句子服务。
- 一个段落的长度不能超过七行，最佳段落长度小于等于四行。
- 段落的句子语气要使用陈述和肯定语气，避免使用感叹语气。
- 段落之间使用一个空行隔开。
- 段落开头不要留出空白字符。
引用
- 引用第三方内容时，应注明出处。
  One man’s constant is another man’s variable. — Alan Perlis
- 如果是全篇转载，请在全文开头显著位置注明作者和出处，并链接至原文。
  本文转载自 WikiQuote
- 使用外部图片时，必须在图片下方或文末标明来源。
  本文部分图片来自 Wikipedia

4. 数值

数值表达应格式统一，千分号规范，货币表达清晰，范围连接明确，变化程度准确。

半角数字：
阿拉伯数字一律使用半角形式。
示例： 1000 元
千分号：
千位以上数值需添加千分号（半角逗号）。
示例： ￥1,258,000
货币格式：
数字前加货币符号或数字后加货币名称。
示例： $1,000 或 1,000 美元
数值范围：
用波浪线（～）或一字线（—）连接，单位或百分号需重复。
示例： 132 kg～234 kg 或 67%～89%
变化程度：
- 增加：用“增加了”表示增量，“增加到”表示定量。
  示例： 增加到过去的两倍（1→2）或 增加了两倍（1→3）
- 减少：用“降低了”表示增量，“降低到”表示定量。
  示例： 降低到百分之八十（100→80）或 降低了百分之八十（100→20）
- 避免“降低 N 倍”或“减少 N 倍”，使用“降低百分之几”或“减少百分之几”。

5. 标点符号

中文全角，英文半角，应遵循标点规范，表达清晰，避免滥用。

全角与半角：
- 中文语句使用全角标点，英文语句使用半角标点。
- 句号、逗号等点号不得出现在行首或标题末尾。
句号：
- 中文句尾用全角句号（。）。
- 括号加注时，句号在括号外。
  示例： 请参照第 1.3 节（见第 26 页）。
逗号与顿号：
- 中文并列词用顿号（、），英文并列词用逗号（,）。
- 避免“一逗到底”，并列词末尾优先用“和”连接。
  示例： Google、Facebook、腾讯和百度。
引号：
- 中文引用用全角双引号（“ ”），嵌套引用用单引号（‘ ’）。
  示例： 他说：“我要放音乐，可萨利说，‘不行！’。”
括号：
- 补充说明用全角圆括号（（）），前后不加空格。
  示例： 请确认所有连接（电缆和接插件）。
冒号：
- 中文用全角冒号（：）引出说明，时间用半角冒号（:）。
  示例： 时间：早上 8:00。
省略号：
- 使用标准省略号（⋯⋯），占两个汉字空间，不与“等”连用。
  示例： 准备了香蕉、苹果、梨⋯⋯
感叹号：
- 避免使用感叹号，不得连用多个感叹号。
破折号：
- 破折号占两个汉字位置，用于解释说明。
  示例： 直觉————尽管它并不总是可靠的————告诉我。
连接号：
- 名词复合用直线连接号（-），数值范围用波浪号（～）或“至”。
  示例： 2009 年～2011 年 或 -20 °C 至 -10 °C

6. 文件命名规则

文件名不得含空格，使用半角字符，避免全角字符。
文件名建议全小写，特殊文件（如README、LICENSE）可大写。
多单词文件名用连词线（-）分隔。
示例： advanced-usage.md
错误示例
- 含空格或中文：名词解释.md
- 大小写混用：TroubleShooting.md
- 使用下划线：advanced_usage.md

四、深入学习

中文技术文档的写作规范, by 阮一峰
产品手册中文写作规范, by 华为
写作规范和格式规范, by DaoCloud
技术写作技巧在日汉翻译中的应用, by 刘方
简体中文规范指南, by lengoo
文档风格指南, by LeanCloud
豌豆荚文案风格指南, by 豌豆荚
中文文案排版指北, by sparanoid
中文排版需求, by W3C
为什么文件名要小写？, by 阮一峰
Google Developer Documentation Style Guide, by Google
出版物上数字用法的规定（国家标准 GBT15835－2011）
GB 3100-1993 国际单位制及其应用