5.6 KiB
5.6 KiB
| title | description | keywords | tags | author | date | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 文档结构 | 本文阐述了技术文档结构的重要性，包括合理使用标题层级、标题描述的规范、段落的组织和目录的编制。强调了标题要简洁明确、避免重复和标点，段落应有单一主题且长度适中，以及目录对快速导航的重要性。 |
|
|
7Wate | 2024-08-07 |
标题
文档结构是技术文档的重要组成部分，一个良好的文档结构能有效帮助读者理解和掌握文档的逻辑和主题。以下是一些关于文档结构的关键要点。
层级
在技术文档中，我们通常使用的**标题层级最多不超过三级。**标题应该按照层级递增，禁止跳级使用。为了保持文档的整洁和一致，除非有特殊需要，否则不建议使用四级标题，可以选择使用列表代替四级标题。
# 文章主标题
## 主要章节的标题
### 子章节的标题
#### 四级标题使用列表代替
描述
标题的描述应简洁明确，可以采用：名词词组、主题词 + 动词、动词 + 主题词、定语 + 主题词、介词 + 定语 + 主题词等形式。它们应能概括反映本章节的中心内容。为了保持标题的一致性，同级别的标题应尽量使用相同的结构。
- 名词词组： 例如「数据结构」、「网络安全」等。
- 主题词 + 动词： 这种形式更加动态，例如「电池充电」、「程序执行」等。
- 动词 + 主题词： 这种形式可以清晰地指示一个操作或行动，例如「安装软件」、「编写代码」等。
- 定语 + 主题词： 这种形式可以给出更多的描述性信息，例如「高效的算法」、「重要的更新」等。
- 介词 + 定语 + 主题词： 这种形式更加详细，例如「对数据结构的理解」、「在网络安全中的防御」等。
注意事项
- **避免重复：**例如，如果一级标题是「数据结构」，那么二级标题应避免再次使用「数据结构」，而应该是更具体的主题，如「数组」、「链表」等。
- 避免使用标点： 例如，不应该写成「数据结构：数组。」，而应该是「数据结构：数组」。
- 避免解释缩略语： 例如，不应该写成「API（Application Programming Interface）」，而应该在正文中解释这个缩略语。
- 添加引导性句子： 例如，在标题「数据结构」和「数组」之间，可以添加一句话：「接下来，我们将详细讨论数据结构中的一种重要类型——数组。」
- 避免孤立编号的标题： 正文不要有孤立的三级和四级标题，每个标题都应该在上一级标题的基础上展开。例如，如果一个部分只有一个三级标题，那么它应该被升级为二级标题。
- 项目列表作为最小编号单位： 不应在项目列表中嵌套任何级别的标题。例如，列表中的每一项都应该是一个完整的思想或概念，而不是一个需要进一步分解的主题。
段落
段落是正文部分的基本构成单元，由多个句子组成。**每个段落应只有一个主题或中心句子，并且中心句子建议放在段落的开头，对全段内容进行概述。段落长度建议在 50~250 字之间，避免超过 300 字。**为提高可读性，段落之间应设置适当的间距。同时，技术描述类主题应考虑先图表、后句子的原则，避免仅依赖段落陈述。
另外，**句子应避免过长，建议不超过 100 字。**使用简单句和并列句，避免复杂的复合句，可以适当地断句，防止句子过长。
示例
1. 数据结构简介
数据结构是计算机科学中的一个核心概念（中心句子）。它是数据值、数据之间的关系、以及对数据进行操作的函数的组织和存储方式。数据结构可以直接或间接地影响程序的效率。在计算机编程中，选择最合适的数据结构对于编写高效的代码至关重要（此段落的长度约为50字）。
2. 数组和链表
数组和链表是两种常见的数据结构（中心句子）。如图1所示，数组是一种线性数据结构，它包含一个或多个元素，每个元素都有一个与之相关联的索引。与此不同，链表由一系列节点组成，每个节点包含一个值和一个指向下一个节点的指针（此段落的长度约为60字，图表在句子之前，便于读者理解）。
数据结构是计算机科学中的一个核心概念。（简单句）
数据结构可以直接或间接地影响程序的效率，因此在编程中选择最合适的数据结构至关重要。（并列句，不超过100字）
数组是一种线性数据结构，包含一个或多个元素，每个元素都有一个与之相关联的索引；链表则由一系列节点组成，每个节点包含一个值和一个指向下一个节点的指针。（并列句，分句处理，避免过长）
目录
文档目录是帮助读者快速浏览和定位章节的重要工具。通过各级标题，我们可以自动生成文档目录。例如，技术手册必须提供总目录，包含所有章节和附录。在网页端发布的技术手册，通常会有全手册导航栏和页内导航栏，相当于总目录和单篇文档目录。这需要根据使用的文档框架自定义文档的标题层级，以确保导航栏能正确显示。
