技术文档中的列表规则

# 技术文档中列表的结构规则

列表在组织信息时，在线性文本和表格之间取得了良好的平衡。对于顺序至关重要的连续操作，使用有序列表：安装步骤、算法。对于没有严格顺序的项集合，使用无序列表：参数、组件。

将列表保持在合理长度。跨越数百行的列表难以浏览——将其拆分为小节或表格。

引导短语作为指南

始终在使用列表前添加一个引导短语来定义其内容。它提供上下文并将各项联系起来。

引导短语示例：

• 执行以下操作以初始化：
• 主函数参数：
• 必需的系统组件：

形成规则：

• 将统一术语（操作、参数、步骤）置于末尾附近。
• 避免指定项数——更改时会过时。
• 如果特定术语不合适，使用通用词：项、部分、步骤。

这确保了一致性并使文本更容易浏览。

名词短语以保持一致性

将列表项表述为名词短语。这创建了统一的结构并提升了可读性。示例转换：

不正确：过程包括：落料、准备、发货。

正确：过程包括以下步骤：落料、准备、发货。

所有行应语法一致，避免混合句子片段和完整句子。

避免列表项中的重复

列表项开头重复的词会产生鹦鹉学舌的效果。将共同词移入引导短语。

示例：

不正确：

• 库 A
• 库 B
• 库 C

正确：安装以下库：

• A
• B
• C

这缩短了文本并突出了关键细节。

单一项目列表

仅含一个项目的独立列表会破坏统一性并暗示格式错误。将项目整合到引导短语中。

示例：不要用列表写“输入参数：user_id”，而是写：“输入参数 user_id 是用户标识符”。

列表中的标点

保持一致：

• 以大写字母开头的行以句号结束。
• 小写开头的行以分号结束。

对于多段落项目，使用第一种风格。这符合技术文档标准。

嵌套列表规则

嵌套简化了层次结构，但需要严格纪律。

编号级别：

• 级别 1：1、2、3
• 级别 2：1.1、1.2
• 级别 3：1.1.1、1.1.2

避免字母和罗马数字——它们会使导航复杂化。

嵌套限制： 不得超过 5 级。如需更多，拆分为小节。四级推荐以获得最佳可读性。

无序列表后： 不要继续编号。这避免了编号歧义。

示例问题结构：

• 级别 1

1.1. 级别 2

- 无序

1.1.1? // 不清楚

关键要点

• 仅对序列使用有序列表；对集合使用无序列表。
• 引导短语中必须有统一术语——不指定数量。
• 列表项使用名词短语，无重复。
• 最大 5 级嵌套；项目符号标记后编号不继续。
• 标点：大写行用句号，小写用分号。

列表提升了技术文本（如文档、指南、文章）的可浏览性。遵循这些规则可最小化中高级开发者和技术专家的认知负担。

— Editorial Team