标准：技术文档（文档结构）

docs/标准/技术文档/文档结构.md

@@ -0,0 +1,100 @@
+---
+id: 文档结构
+title: 文档结构
+sidebar_position: 3
+data: 2022年3月8日
+---
+
+## 标题
+
+标题在技术文档中的地位非常重要，文档工程师要设计合理的标题层级和标题描述，帮助读者理清整篇文档的逻辑，使文章结构一目了然。
+
+### 标题的层级
+
+技术文档中使用标题最多不超过四级。**标题从一级开始递增使用，禁止跳级使用**。例如：一级标题下面不能直接使用三级标题；二级标题下面不能直接使用四级标题。
+
+- 一级标题：即文章标题
+- 二级标题：文章正文部分的标题
+- 三级标题：二级标题下面一级的小标题
+- 四级标题：三级标题下面一级的小标题
+
+下图为在 Markdown 技术文档中使用标题的示例，左侧是编辑文字，右侧是预览效果：
+
+![heading-levels](https://static.7wate.com/img/2022/03/08/ddcfa173863fd.png)
+
+为避免出现过于复杂的章节，若无特殊需要，不建议使用四级标题。如果三级标题下有并列性的内容，建议使用列表 (list) 代替四级标题。如下图中，若内容 A、B、C 的篇幅不长，则右侧的标题样式比左侧的标题样式要好。
+
+![headings-or-lists](https://static.7wate.com/img/2022/03/08/dc2f9abce9d17.png)
+
+### 标题的描述
+
+技术文档中的标题包括但不限于以下几种描述：
+
+- 名词词组，如“…概述”、“…背景”、“…原理”
+- 主题词+动词，如“A 工具安装”、“A 工具部署”、“A 工具配置”
+- 动词+主题词，如“配置 MySQL 数据库”
+- 定语+主题词，如“A 工具的安装”，“A 工具的架构”
+- 介词+定语+主题词，如“对机器配置的要求”
+
+标题描述的设计并无严格的模板，只要遵循以下几个原则即可：
+
+- 标题能够概括反映本章节的中心内容
+- 标题简洁扼要、涵义明确
+- 同级别的标题尽量使用相同的结构
+- 标题描述**操作任务**时建议使用“动词+主题词”结构，不建议使用名词词组
+
+### 使用标题的注意事项
+
+技术文档中使用标题主要有以下几个注意事项：
+
+- 下级标题禁止重复上一级标题的内容
+- 不建议标题以标点符号（如句号或问号）结尾
+- 不建议在标题中解释缩略语
+- 标题与标题之间应该有引导介绍性的句子。例如，一级标题和二级标题之间应有引言内容，二级标题和三级标题之间应有正文内容
+- 标题要避免孤立编号（即同级标题只有一个），正文不要有孤立的三级标题和四级标题
+- 项目列表是最小编号单位，因此项目列表下禁止嵌套任何级别的标题
+
+## 段落
+
+段落是正文部分的基本构成单元之一，由多个句子组成。段落写作要求如下：
+
+- 一个段落只能有一个主题，或一个中心句子。
+- 段落的中心句子建议放在段首，对全段内容进行概述。后面陈述的句子为核心句服务。
+- 一个段落的长度建议在 50～200 字之间，尽量不要超过 250 字。（Word 里统计字数）
+- 一个段落里避免只有一个句子。如果句子很长，要避免”**一逗到底**”的情况，合理断句。
+- 段落之间建议设置合适的间距，提高可读性。
+- 段落的句子语气应该使用陈述和肯定语气，避免使用感叹语气。
+- 技术文档的段落开头不建议缩进，顶格开始即可。
+- 对于技术描述类主题，应考虑先图表，后句子的原则，不要单一地使用段落来陈述主题。
+
+## 句子
+
+句子以句号结尾，句号表示句子意思已完成。句子写作要求如下：
+
+- 句子要避免使用长句。一个句子建议不超过 100 字。
+- 句子要使用简单句和并列句，避免使用复合句。
+- 善于断句，避免“一逗到底”的现象。
+
+【错误示例】原因是 DM 需要保存同步的 binlog position 信息，但是 MySQL binlog position 官方定义使用 uint32 存储，所以超过 4G 部分的 binlog position 的 offset 值会溢出，就会存储的是一个错误的 binlog position，在重启 task 或者 dm-worker 后，需要使用该 binlog position 重新解析 binlog/relay log，进而出现上面的错误。
+
+【分析】以上句子为多个分句构成的复合句。“一逗到底”的情况增加了理解整体句群含义的难度。这种情况下，应该在适当的地方进行断句，并添加“这”、“其”等代词，合理切分句与句之间的逻辑。
+
+【修改建议】由于 DM 需要保存同步的 binlog position 信息，且 MySQL binlog position 官方定义使用 uint32 存储，因此超过 4G 部分的 binlog position 的 offset 值会溢出。这会导致存储的是一个错误的 binlog position。在重启 task 或者 dm-worker 后，需要使用该 binlog position 重新解析 binlog/relay log，进而出现上面的错误。
+
+## 目录
+
+文档目录可以**通过各级标题自动生成**，帮助用户快速浏览全文结构和定位章节。
+
+对于一本技术手册而言，必须提供总目录（包含所有章节及附录）。如果是安装手册等还需要提供图目录、表目录。
+
+发布在网页端的技术手册，两侧一般都配置有导航栏，包括**全手册导航栏**及**页内导航栏**。这两种导航栏相当于技术手册的**总目录**及**单篇文档目录**。
+
+如下是 PingCAP 技术文档站的目录实现：
+
+![table-of-contents](https://static.7wate.com/img/2022/03/08/9483ae8017108.jpg)
+
+注意：
+
+在实际操作中，文档右侧导航栏能显示哪些[标题层级](https://zh-style-guide.readthedocs.io/zh_CN/latest/标题.html#id2)，由使用的文档框架决定。例如 [Docusaurus 框架](https://docusaurus.io/docs/en/navigation)，虽然正文中对标题级别没有限制，但在右侧导航栏只支持显示二级标题 (##) 和三级标题 (###)，一级标题 (#) 和四级标题 (####) 不会出现在右侧导航栏中。
+
+因此，建议各公司**根据使用的文档框架自定义文档的标题层级**，如果右侧导航栏无法显示一级标题 (#)，则可以自定义文档中的一级标题为 ##，二级标题为 ###，以此类推。