TiDB 中文技术文档写作风格指南
本文为在 pingcap/docs-cn 仓库中撰写、编辑或评审中文 Markdown 文档提供细则。
本文中标注 (markdownlint MDxxx) 的条目由 ./scripts/markdownlint 强制校验,提交前请确保通过。
基本原则
- 优先保证技术事实准确;不确定时标记为“需要确认”,不要猜测。
- 站在用户角度写作,优先说明用户关心的前提、步骤、结果、限制和风险。
- 使用客观、礼貌、清晰的语气,不使用营销式、夸张式或情绪化表达。
- 使用对话式但不口语化的表达,避免冗长、随意、玩笑化或内部黑话。
- 尽量使用主动语态,明确主语、动作和宾语。
- 同一篇文档中的术语、称呼、格式、链接描述和结构必须保持一致。
- 修改已有文档时,优先保持原文档的信息架构和风格,不要无理由大幅改写。
信息准确性
- 新增或修改功能、变量、参数、限制、默认值、版本信息前,必须确认来源。
- 涉及版本变化时,必须说明从哪个版本开始生效或在哪些版本中支持。
- 涉及风险、限制、兼容性、数据丢失、性能影响时,必须明确说明影响范围和触发条件。
- 不要把内部实现细节写成用户可见行为,除非该实现会影响用户决策或操作。
- 不要使用模糊判断替代事实,例如“性能很好”“大量提升”“可能更稳定”。
- 有可量化信息时,优先使用具体数据、条件和示例说明影响。
文档结构
- 文档必须有清晰的标题层级,标题最多使用四级,且逐级递增、不得跳级 (markdownlint MD001)。
- 每篇文档只能有一个一级标题 (markdownlint MD025)。
- 一级标题必须与元数据中的
title保持一致。 - 下级标题不要重复上级标题的内容;不要连续出现内容相同的标题 (markdownlint MD024)。
- 标题末尾不要使用标点符号;FAQ 问题标题可以使用问号 (markdownlint MD026)。
- 标题不要解释缩略语,缩略语解释应放在正文首次出现处。
- 标题之间必须有正文或引导句,不要让两个标题直接相连;标题上下须各空一行 (markdownlint MD022)。
- 避免孤立标题,即同一级标题不要只出现一个。
- 列表项下不要嵌套标题。
标题写法
- 标题必须能概括本节核心内容。
- 标题应简洁明确,避免冗长。
- 同级标题应尽量使用相同句式。
- 操作型标题建议使用“动词 + 主题词”结构,例如“配置 MySQL 数据库”。
- 概念型标题可以使用名词词组,例如“架构”“使用限制”“工作原理”。
元数据
- 发布的正文 Markdown 文档开头必须包含元数据(front matter)。
TOC*.md、README.md、resources/doc-templates/以及.agents/等非发布文档不要求遵循此项。 - 元数据必须使用
---包裹。 - 元数据至少包含
title和summary。 title必须与一级标题一致。summary必须是完整句子,应概括全文,尽量包含核心关键词,并以句号结尾。summary不要以>、*、#、-、[等特殊字符开头;如必须,则用引号包裹整个summary内容。- 只有文档路径或文件名变更时才添加
aliases。 - 不要自行添加未约定的元数据字段。
段落和句子
- 一个段落只表达一个主题。
- 段落之间使用一个空行隔开。
- 段落开头不缩进。
- 句子应简短清楚,避免“一逗到底”。
- 长句必须拆分,并补充必要的逻辑连接。
- 优先使用简单句和并列句,避免复杂嵌套句。
- 技术描述较复杂时,优先考虑表格、列表或图示,而不是长段落。
- 删除对理解没有帮助的重复信息和空泛表达。
用词规则
- 避免使用行话、黑话、俚语、网络流行语和内部简称。
- 避免使用主观或绝对化词语,例如“最佳”“最好”“最先进”“最高水平”。
- 避免使用模糊程度词,例如“很多”“大量”“数倍”。
- 必须明确“其”“该”“此”“这”等代词指代的对象。
- 不要使用过多修饰语堆叠名词。
- 同一文档中人称必须一致。
- 在没有歧义的情况下,使用“你”指代用户。
- 不建议使用“我”指代文档作者。
- 尽量避免使用“我们”,因为不清楚指的是谁。
- 术语、缩写和产品名统一以
resources/tidb-terms.md(TiDB 中英术语表)为准;术语缺失或有歧义时,保留原文并标注,不要自行生造译法。
空格和空行
- 中文字符与中文字符之间不要加半角空格。
- 中文标点前后不要加空格。
- 英文字符、阿拉伯数字与中文之间通常需要加半角空格。
- 位于句首的英文或数字左侧不加空格。
- 英文或数字右侧紧跟全角标点时,右侧不加空格。
- 除缩进、列表和代码块外,禁止连续出现两个及以上半角空格。
- 不同段落之间使用一个空行。
- 标题、正文、列表、表格、图片、代码块等不同内容块之间使用一个空行 (markdownlint MD022/MD031/MD032)。
- 禁止连续出现两个及以上空行 (markdownlint MD012)。
- 任何位置(包括代码块内)都不要使用 Tab 制表符,统一用空格 (markdownlint MD010)。
列表
- 有 3 项或更多并列信息时,优先使用列表。
- 顺序不重要时使用无序列表。
- 必须按顺序操作、排名或后文引用编号时,才使用有序列表;有序列表须从 1 开始并依次递增 (markdownlint MD029)。
- 列表标识符(
-、*、+或数字)后只空一格 (markdownlint MD030)。 - 列表前必须有清晰的引导句;列表前后须各空一行 (markdownlint MD032)。
- 并列列表项应使用相似的语法结构。
- 列表项长度应尽量接近。
- 不要在每个列表项开头重复相同词语。
- 每个列表项只表达一个点。
- 多级列表缩进使用 4 个空格;
TOC.md使用 2 个空格缩进 (markdownlint MD007)。 - 不要把过长段落硬拆成列表;列表必须体现并列关系或步骤关系。
表格和图片
- 表格必须有表头。
- 表格内容保持左对齐。
- 表格单元格内容应简洁,避免长段落。
- 不要出现空白单元格;无内容时写“无”或说明特定符号含义。
- 不要使用“同上”代替重复内容。
- 表格前后必须各空一行。
- 图片必须与正文内容直接相关。
- 图片前后必须各空一行。
- 图片必须提供替代文字(alt text)。
- 外部图片必须标明来源。
- 图片说明必须与图片内容一致。
注意、警告和建议
- 只有需要强调风险、限制、补充说明或最佳实践时,才使用注意类提示。
- 不要滥用注意、警告、建议或错误提示。
- 不建议连续使用多个提示块。
- 提示内容应简短,建议不超过 4 行。
- 提示块中不要包含表格或图片。
- 高风险行为使用“警告”,例如可能导致数据丢失、服务中断、不可逆操作。
- 一般补充说明使用“注意”。
- 可选优化做法使用“建议”。
- 错误场景说明使用“错误”。
推荐格式:
注意:
说明内容。
代码和命令
- 行内参数、变量、配置项、字段名、表名、库名、文件名、SQL 关键字使用反引号。
- UI 界面元素(按钮、菜单项、字段标签、对话框名称等)使用加粗,例如 保存,以与代码字体区分。
- 多行代码、命令输出、配置片段使用代码块。
- 代码块前后必须各空一行 (markdownlint MD031)。
- 代码块必须标明语言,例如
sql、shell、bash、yaml。 - 属于列表项的代码块,需要在列表缩进基础上再缩进 4 个空格。
- 可复制执行的代码块中尽量不要写注释。
- 代码注释应尽量写到正文中解释,避免影响用户复制执行。
- 一个代码块中尽量只放一条命令,便于解释和排错。
- 多行 SQL 不要使用
&&或&连接。
链接
- 链接文本必须描述目标页面内容,不要使用“此处”“这里”“trouble-shooting.md”作为链接文本。
- 同类链接描述应保持一致,例如统一使用“详情参见”。
- 链接到站内其他文档时,使用从根目录开始的相对路径,例如
/foo/bar.md。 - 链接到长文档时,尽量链接到具体标题锚点。
- 链接到同一文档标题时,直接使用
#标题锚点。 - 锚点中的英文字母必须小写。
- 锚点中的空格使用连字符
-替换。 - 锚点中保留字母、数字、下划线、连字符和常用中文,其他特殊符号删除。
- 不要使用裸露的 URL:需要点击时用尖括号包裹(
<URL>),不需要点击时用反引号包裹 (markdownlint MD034)。 - 减少不必要的外部链接,避免外部页面失效。
- 引用第三方内容、转载内容或外部图片时,必须注明来源。
缩略语
- 不建议在标题中解释英文缩略语。
- 正文中第一次出现英文缩略语时,应解释完整含义。
- 如果后文将使用缩略语代称某个长名称,首次出现时必须说明。
- 不要使用不规范缩写,例如用
16c32g表示16 核、32 GB。 - 产品或工具名称第一次出现时使用全称,后文可使用约定缩写。
- 缩略语必须符合产品术语表或既有写法。
数字、日期和单位
- 数字与中文之间通常加半角空格。
- 统计表、版本号、百分比、小数、比例等使用阿拉伯数字。
- 固定表达或约数使用文字型数字,例如“几十个”“一百多个”。
- 多位数值建议使用英文逗号分节,例如
2,345,567。 - 数字范围使用
~,并尽量两端都写单位,例如64 MB~128 MB。 - 区分“增加了”和“增加到”,“降低了”和“降低到”。
- 不要写“降低 N 倍”或“减少 N 倍”,应改为“降低百分之几”或“减少百分之几”。
- 日期使用阿拉伯数字,例如
2003 年 7 月 30 日。 - 表格或索引中的日期可使用
2003-07-30。 - 物理量必须使用阿拉伯数字和合法单位。
- 数值与单位之间通常空一格,例如
8 MB、10 GB。 - 百分号、摄氏度、角度与数字之间不空格,例如
100%、37°C。
标点和中英文混排
- 三个或三个以上中文并列项使用顿号,不要用逗号或斜杠。
- 不要连续使用冒号。
- 中文技术文档统一使用弯引号,不使用直角引号。
- 破折号前后不空格。
- 中文正文使用省略号字符
……(两个 U+2026),不要使用 ASCII 句点...或......;代码和命令输出中保留原始字符。 - 多个并列项不要用
/连接,应使用顿号或“和”。 - 斜杠
/两侧不加空格。 - 自定义变量或参数建议使用
${variable},不要用裸变量名或尖括号包裹。
文件名和产品名
- Markdown 文件名应简要概括文档内容。
- 文件名一般不超过 4 个英文单词。
- 除
TOC.md、CONTRIBUTING.md、README.md等约定文件外,文件名使用全小写。 - 多个英文单词之间使用短划线
-。 - 文件名不要使用下划线
_。 - Markdown 文件后缀必须为
.md。 - 产品、工具、组件名称必须使用官方写法,注意大小写。
- 不要随意改写产品名、工具名或缩写。
- MySQL 版本号应写为
MySQL 8.0、MySQL 8.4或MySQL 8.x,不要添加v前缀。 - 示例:应写
MySQL、LinkedIn、PostgreSQL,不要写mysql、Linkedin、postgresql。
最终检查清单
完成文档撰写、编辑或评审前,请确认:
- [ ] 内容满足明确的用户需求,并适合目标读者。
- [ ] 技术事实准确,修改未改变预期的产品行为和适用范围。
- [ ] 文档结构符合文档类型,标题层级和写法符合规范。
- [ ] 操作步骤清晰、可执行,且所需的前提条件和上下文位于相关步骤之前。
- [ ] 术语、产品名称和版本写法准确且一致。
- [ ] 命令、代码、配置项、API 字段、UI 文案和字面值保持正确。
- [ ] 链接、格式、列表、注意、警告、图片和替代文字符合仓库规范。
- [ ] 语言清晰、简洁、准确且易于理解。
- [ ] 已检查是否需要同步更新相关文档、TOC、别名或交叉引用。
本文来自 PingCAP / TiDB 文档贡献者,按 CC BY-SA 3.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
