标题

文档结构是技术文档的重要组成部分,一个良好的文档结构能有效帮助读者理解和掌握文档的逻辑和主题。以下是一些关于文档结构的关键要点。

层级

在技术文档中,我们通常使用的**标题层级最多不超过三级。**标题应该按照层级递增,禁止跳级使用。为了保持文档的整洁和一致,除非有特殊需要,否则不建议使用四级标题,可以选择使用列表代替四级标题。

# 文章主标题
## 主要章节的标题
### 子章节的标题
#### 四级标题使用列表代替

描述

标题的描述应简洁明确,可以采用:名词词组、主题词 + 动词、动词 + 主题词、定语 + 主题词、介词 + 定语 + 主题词等形式。它们应能概括反映本章节的中心内容。为了保持标题的一致性,同级别的标题应尽量使用相同的结构。

  1. 名词词组: 例如「数据结构」、「网络安全」等。
  2. 主题词 + 动词: 这种形式更加动态,例如「电池充电」、「程序执行」等。
  3. 动词 + 主题词: 这种形式可以清晰地指示一个操作或行动,例如「安装软件」、「编写代码」等。
  4. 定语 + 主题词: 这种形式可以给出更多的描述性信息,例如「高效的算法」、「重要的更新」等。
  5. 介词 + 定语 + 主题词: 这种形式更加详细,例如「对数据结构的理解」、「在网络安全中的防御」等。

注意事项

  1. **避免重复:**例如,如果一级标题是「数据结构」,那么二级标题应避免再次使用「数据结构」,而应该是更具体的主题,如「数组」、「链表」等。
  2. 避免使用标点: 例如,不应该写成「数据结构:数组。」,而应该是「数据结构:数组」。
  3. 避免解释缩略语: 例如,不应该写成「API(Application Programming Interface)」,而应该在正文中解释这个缩略语。
  4. 添加引导性句子: 例如,在标题「数据结构」和「数组」之间,可以添加一句话:「接下来,我们将详细讨论数据结构中的一种重要类型——数组。」
  5. 避免孤立编号的标题: 正文不要有孤立的三级和四级标题,每个标题都应该在上一级标题的基础上展开。例如,如果一个部分只有一个三级标题,那么它应该被升级为二级标题。
  6. 项目列表作为最小编号单位: 不应在项目列表中嵌套任何级别的标题。例如,列表中的每一项都应该是一个完整的思想或概念,而不是一个需要进一步分解的主题。

段落

段落是正文部分的基本构成单元,由多个句子组成。**每个段落应只有一个主题或中心句子,并且中心句子建议放在段落的开头,对全段内容进行概述。段落长度建议在 50~250 字之间,避免超过 300 字。**为提高可读性,段落之间应设置适当的间距。同时,技术描述类主题应考虑先图表、后句子的原则,避免仅依赖段落陈述。

另外,**句子应避免过长,建议不超过 100 字。**使用简单句和并列句,避免复杂的复合句,可以适当地断句,防止句子过长。

示例

1. 数据结构简介
 
数据结构是计算机科学中的一个核心概念(中心句子)。它是数据值、数据之间的关系、以及对数据进行操作的函数的组织和存储方式。数据结构可以直接或间接地影响程序的效率。在计算机编程中,选择最合适的数据结构对于编写高效的代码至关重要(此段落的长度约为50字)。
 
2. 数组和链表
 
数组和链表是两种常见的数据结构(中心句子)。如图1所示,数组是一种线性数据结构,它包含一个或多个元素,每个元素都有一个与之相关联的索引。与此不同,链表由一系列节点组成,每个节点包含一个值和一个指向下一个节点的指针(此段落的长度约为60字,图表在句子之前,便于读者理解)。
数据结构是计算机科学中的一个核心概念。(简单句)
 
数据结构可以直接或间接地影响程序的效率,因此在编程中选择最合适的数据结构至关重要。(并列句,不超过100字)
 
数组是一种线性数据结构,包含一个或多个元素,每个元素都有一个与之相关联的索引;链表则由一系列节点组成,每个节点包含一个值和一个指向下一个节点的指针。(并列句,分句处理,避免过长)

目录

文档目录是帮助读者快速浏览和定位章节的重要工具。通过各级标题,我们可以自动生成文档目录。例如,技术手册必须提供总目录,包含所有章节和附录。在网页端发布的技术手册,通常会有全手册导航栏和页内导航栏,相当于总目录和单篇文档目录。这需要根据使用的文档框架自定义文档的标题层级,以确保导航栏能正确显示。

table-of-contents