diff --git a/docs/标准/技术文档/文档结构.md b/docs/标准/技术文档/文档结构.md new file mode 100644 index 00000000..bbf5c539 --- /dev/null +++ b/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),虽然正文中对标题级别没有限制,但在右侧导航栏只支持显示二级标题 (##) 和三级标题 (###),一级标题 (#) 和四级标题 (####) 不会出现在右侧导航栏中。 + +因此,建议各公司**根据使用的文档框架自定义文档的标题层级**,如果右侧导航栏无法显示一级标题 (#),则可以自定义文档中的一级标题为 ##,二级标题为 ###,以此类推。 \ No newline at end of file