大网数据广告活动
数据库部署与 SQL 参考

TiDB 中文技术文档写作风格指南

· 52CE 我爱测

# TiDB 中文技术文档写作风格指南 本文为在 仓库中撰写、编辑或评审中文 Markdown 文档提供细则。 本文中标注 的条目由 强制校验,提交前请确保通过。 ## 基本原则 - 优先保证技术事实准确;不确定时标记为“需要确认”,不要猜测。 - 站在用户角度写作,优先说明用户关心的前提、步骤、结果、限制和风险。 - 使用客观、礼貌、清晰的语气,不使用营销式、夸张式或情绪化表达。 - 使用对话式但不口语化的表达,避免冗长、随意、玩笑化

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 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
PingCAP / TiDB 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY-SA 3.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。