6.1 KiB
| id | title | sidebar_position | data |
|---|---|---|---|
| 文档结构 | 文档结构 | 3 | 2022年3月8日 |
标题
标题在技术文档中的地位非常重要，文档工程师要设计合理的标题层级和标题描述，帮助读者理清整篇文档的逻辑，使文章结构一目了然。
标题的层级
技术文档中使用标题最多不超过四级。标题从一级开始递增使用，禁止跳级使用。例如：一级标题下面不能直接使用三级标题；二级标题下面不能直接使用四级标题。
- 一级标题：即文章标题
- 二级标题：文章正文部分的标题
- 三级标题：二级标题下面一级的小标题
- 四级标题：三级标题下面一级的小标题
下图为在 Markdown 技术文档中使用标题的示例，左侧是编辑文字，右侧是预览效果：
为避免出现过于复杂的章节，若无特殊需要，不建议使用四级标题。如果三级标题下有并列性的内容，建议使用列表 (list) 代替四级标题。如下图中，若内容 A、B、C 的篇幅不长，则右侧的标题样式比左侧的标题样式要好。
标题的描述
技术文档中的标题包括但不限于以下几种描述：
- 名词词组，如“…概述”、“…背景”、“…原理”
- 主题词+动词，如“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 技术文档站的目录实现：
注意：
在实际操作中，文档右侧导航栏能显示哪些标题层级，由使用的文档框架决定。例如 Docusaurus 框架，虽然正文中对标题级别没有限制，但在右侧导航栏只支持显示二级标题 (##) 和三级标题 (###)，一级标题 (#) 和四级标题 (####) 不会出现在右侧导航栏中。
因此，建议各公司根据使用的文档框架自定义文档的标题层级，如果右侧导航栏无法显示一级标题 (#)，则可以自定义文档中的一级标题为 ##，二级标题为 ###，以此类推。