wiki/Tech/software-engineering/技术文档/文档结构.md

---
title: 文档结构
description: 文档结构
keywords:
  - 文档
  - 结构
tags:
  - 软件工程/技术文档
sidebar_position: 3
author: 7Wate
date: 2023-06-26
---

## 标题

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

### 层级

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

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

### 描述

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

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

### 注意事项

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

## 段落

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

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

### 示例

```markdown
1. 数据结构简介

数据结构是计算机科学中的一个核心概念（中心句子）。它是数据值、数据之间的关系、以及对数据进行操作的函数的组织和存储方式。数据结构可以直接或间接地影响程序的效率。在计算机编程中，选择最合适的数据结构对于编写高效的代码至关重要（此段落的长度约为50字）。

2. 数组和链表

数组和链表是两种常见的数据结构（中心句子）。如图1所示，数组是一种线性数据结构，它包含一个或多个元素，每个元素都有一个与之相关联的索引。与此不同，链表由一系列节点组成，每个节点包含一个值和一个指向下一个节点的指针（此段落的长度约为60字，图表在句子之前，便于读者理解）。
```

```markdown
数据结构是计算机科学中的一个核心概念。（简单句）

数据结构可以直接或间接地影响程序的效率，因此在编程中选择最合适的数据结构至关重要。（并列句，不超过100字）

数组是一种线性数据结构，包含一个或多个元素，每个元素都有一个与之相关联的索引；链表则由一系列节点组成，每个节点包含一个值和一个指向下一个节点的指针。（并列句，分句处理，避免过长）
```

## 目录

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

![table-of-contents](https://static.7wate.com/img/2022/03/08/9483ae8017108.jpg)