100 lines
6.1 KiB
Markdown
100 lines
6.1 KiB
Markdown
---
|
||
id: 文档结构
|
||
title: 文档结构
|
||
sidebar_position: 3
|
||
data: 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 技术文档站的目录实现：
|
||
|
||
|
||
|
||
注意：
|
||
|
||
在实际操作中，文档右侧导航栏能显示哪些[标题层级](https://zh-style-guide.readthedocs.io/zh_CN/latest/标题.html#id2)，由使用的文档框架决定。例如 [Docusaurus 框架](https://docusaurus.io/docs/en/navigation)，虽然正文中对标题级别没有限制，但在右侧导航栏只支持显示二级标题 (##) 和三级标题 (###)，一级标题 (#) 和四级标题 (####) 不会出现在右侧导航栏中。
|
||
|
||
因此，建议各公司**根据使用的文档框架自定义文档的标题层级**，如果右侧导航栏无法显示一级标题 (#)，则可以自定义文档中的一级标题为 ##，二级标题为 ###，以此类推。 |