代码中如何让无序标记的内容并排_英语技术文档中如何正确使用无序列表和有序列表？...

Foreword

之前跟大家分享过英语技术文档中如何正确使用时态和英语技术文档中如何正确使用人称，这一篇再跟大家分享一下如何正确使用无序列表和有序列表。

其实，在技术文档中，除了无序列表和有序列表，另一种常见的列表是定义列表 (Definition list，Google 的 Style Guide 中称作 Description list)。定义列表的使用注意规范即可，相对简单，本文暂不作展开，主要聊一聊无序列表和有序列表。

你可能会说了，无序列表和有序列表很容易分清啊，无顺序要求的用无序列表，有顺序要求的用有序列表就好了。确实，是这么个逻辑。但问题在于，有时你不知道它是无序的还是有序的。

笔者在工作中发现，英语技术文档中列表的使用可能会出现以下问题：

• 不清楚使用情境，不该用列表的地方却用了。
• 误用列表，无序列表和有序列表选择错误。
• 选对了列表，但在大小写、标点等格式上不规范。

于是，笔者研究了下 IBM 和 Google 的文档规范中对有序列表和无序列表的说明，在这里分享给大家。本文谈到的基本规范是通用的，有一些具体的格式是基于 GitHub + Markdown 这种文档解决方案来说的，相关之处会详细说明。本文结构如下：

1. 什么是无序列表和有序列表
2. 为什么要规范使用列表
3. 何时使用无序列表
4. 何时使用有序列表
5. 常用的列表格式规范

1. 什么是无序列表和有序列表

• 无序列表，即 Unordered lists 或 Bulleted lists。百度百科里对它的定义为：
  “无序列表是一个没有特定顺序的列表项的集合，也称为项目列表。在无序列表中，各个列表之间属于并列关系，没有先后顺序之分，它们之间以一个项目符号来标记。”
• 有序列表，即 Ordered lists 或 Numbered lists。顾名思义，即有顺序的列表，通常是用数字来标示顺序的列表，在技术文档中常用于描述具体的操作步骤。

2. 为什么要规范使用列表

在技术文档中，规范地使用无序列表和有序列表有助于帮助文档读者快速、正确、清晰地理解要传达的意思。而如果使用不当，就可能会误导读者，给读者造成困惑，甚至理解错误，影响文档和产品的使用体验。

• 如果在本该使用无序列表的地方用了有序列表，那么用户可能会想：
  看内容感觉好像不存在顺序关系，可既然用了有序列表，是不是表明这些项之间存在优先级关系或是先后顺序呢？
• 如果在本该使用有序列表的地方用了无序列表，那么用户可能会想：
  看列表格式好像是没有顺序关系，可是看内容好像又应该是有先后顺序的，到底是要表达怎样的关系呢？或者，虽然不是有顺序的操作步骤，但各项之间存在某种逻辑关系，也需要用有序列表来传达，此时，如果用无序列表就会丢失这么一层关系。

3. 何时使用无序列表

根据 IBM Style Guide，当列表项之间的顺序不重要时，使用无序列表。根据 Google 的 Style Guide，无序列表用于既非顺序列也非选项的列表项。

需要注意的是，即便在无序列表中，如果可能的话，也应该尽量按某种逻辑来展示各项。如果没有更好的选择，可以按字母顺序来排列。

如果列表是有依据的分组，但该依据并非显而易见，最好说明一下。

正确示例：

When you configure the computer, you can use the program to set the following items:

• Date and time
• Passwords
• Drive startup sequence

4. 何时使用有序列表

当各项之间的顺序很重要时，使用有序列表。相关的场景如下：

1. 必须按顺序操作的步骤（最常用）
2. 对多项内容进行的排名
3. 列表项中的内容是之后需要引用的规则或其它信息

前两个场景比较好理解，第 3 个场景常用于列表项为一些规则时，比如 4 条规则，然后，在下文或其它文档中需要引用该规则列表中的某项规则。此时有个数字编号就很方便引用了，通常列表中的第几条对应的就是规则几，如列表中的第 3 条在引用时可以说“规则 3”。

正确示例：

Write comment statements according to the following rules:

1. Use an asterisk in the first column.
2. Do not exceed 80 characters.
3. Do not place a comment statement between an instruction and its continuation line.

5. 常用的列表格式规范

现在大家已经清楚了何时使用无序列表和有序列表，再来看看使用列表时还需注意的一些格式规范：

• 列表前的介绍性句子
• 列表内容的大小写
• 列表内容的平行语法
• 列表项的标点
• 列表的长度
• 列表项包含多个段落
• 列表嵌套

列表前的介绍性句子

大多数情况下，在列表前都需要有一个介绍性的句子。

• 如果列表不是操作步骤，通常需要在列表前加一个介绍性的句子。
• 如果在 Task 类型的 topic 中，列表紧跟着 "Before you begin," "Prerequisites," "Restrictions,"，那么列表前可以加介绍性句子，也可以不加。

列表前的介绍性引入句子可以以冒号结束，也可以以句号结束。通常，如果紧接着列表内容，则使用冒号；如果在介绍性句子和列表之间还有其它内容（如注意事项），则使用句号。

错误示例：

Use the Submit button to:

• submit the form
• indicate that you're done
• allow the next person to enter their data

正确示例：

Use the Submit button for any of the following purposes:

• To submit the form.
• To indicate that you're done.
• To allow the next person to enter their data.

对于列表前的介绍性引入句子，IBM 和 Google 的规范都建议尽量使用一个完整的句子，而非需要列表项才能补全的句子片段。例如，以 To 开头的不定式短语，可以使用，但不建议使用。

不建议使用：

To get the USB driver:

1. Click Tools > Android > SDK Manager.
2. Select Google USB Driver and then click OK.

建议使用：

To get the USB driver, follow these steps:

1. Click Tools > Android > SDK Manager.
2. Select Google USB Driver and then click OK.

列表内容的大小写

在垂直列表中，每个列表项第一个单词的首字母需大写，特殊情况除外。

正确示例：

The routine makes the following conversions:

• An EBCDIC value to a real number
• A real number to an EBCDIC value
• An EBCDIC value to an integer
• An integer to an EBCDIC value

列表内容的平行语法

在同一个列表中，各列表项尽量使用相同的语法或结构，或者说，尽量让各列表项在语法上保持平行。例如，尽量做到要么各列表项都是完整的句子，要么都不是。

错误示例：

XYZ Manager has the following features:

• A graphical user interface.
• It is compatible with ABC Manager.
• It can be used on many types of systems.

正确示例：

XYZ Manager has the following features:

• It has a graphical user interface.
• It is compatible with ABC Manager.
• It can be used on many types of systems.

列表项的标点

列表项末尾的标点要根据列表类型和具体内容而定。

• 如果列表项都是完整的句子，在末尾加句号。
• 如果列表项是一个短语，末尾不加标点。
• 如果列表项不包含动词，末尾不加标点。
• 如果列表项只包含一个词，末尾不加标点。
• 如果列表中的某个列表项以短语开头，一个或多个短语之后紧接的是完整的句子。此时，短语和完整句子后面都加句号。

错误示例：

Session management can store session-related information in several ways:

• In application server memory. This storage option is local to the application server and cannot be shared with other application servers.
• In a database
• In another WebSphere Application Server instance

正确示例：

Session management can store session-related information in several ways:

• In application server memory. This storage option is local to the application server and cannot be shared with other application servers.
• In a database.
• In another WebSphere Application Server instance.

列表的长度

• 有序列表中，需至少包含两个列表项。
• 无序列表中，如果是为了跟同一部分其它无序列表的格式保持一致，可以只包含一个列表项。
• 列表不可过长，根据 IBM 的文档规范，最多可包含 9 个列表项。如果列表项的数目超过了此限制，可考虑使用多个列表。
• 如果是 Reference 文档中按字母顺序排列的列表，那么列表较长也是可以接受的。因为用户不会从头读到尾，而是会根据字母顺序找到所需的部分。

列表项包含多个段落

列表项可能包含多个段落，常见于对列表项的进一步解释说明。例如：

• This list item is a single paragraph.
• This list item contains multiple paragraphs.
  As you can see!
• This is another list item that's only one paragraph long.

在 Markdown 文件中，需注意多个段落前的空格缩进，通常为两个或四个空格；还需注意给多的段落前添加空行，否则也很可能会影响格式的正确显示。某个列表项所包含的段落，需与该列表项开始的内容在格式上对齐。

笔者在使用 GitHub 和 Markdown 的实践中，通常会统一空四个空格，这样无论是有序列表还是无序列表，均可正确显示格式。不同文档发布平台可能要求不同，知晓并遵守规范即可。

列表嵌套

关于无序列表和有序列表中的嵌套列表，IBM 要求尽量避免列表嵌套超过两级，最多三级。Google 规范中无明确说明，但通常最多三级。

在 Markdown 文件中，嵌套列表时需注意嵌套项的空格缩进。不同的网站可能有不同的要求，例如嵌套的无序列表缩进两个空格即可。

大多数情况下，如果嵌套项比上一级缩进四个空格，格式可正确显示。

正确示例 1：

1. Remove the cover.
2. Install the adapter:
   1. Insert the adapter into the slot.
   2. Connect the adapter cable to the connector on the system board.
3. Install the cover.

正确示例 2：

The following choices are on the menu:

• DPI settings
  • Set Write Access Managers
  • Set Trap Receivers
• Reset configuration

Afterword

除了上文提到的列表类型之外，Google 的规范中还提到一种字母列表 (Lettered list)，指的是一些可供选择的列表项，尤其指互斥的选项。这类列表通常使用大写的 A、B、C、D 来展示各项，类似于试卷中常出现的选择题。

看到这里，想必大家对技术文档中无序列表和有序列表的使用有了更多的了解。如果你在技术文档写作的实践或研究中有不同的见解，或者想跟大家分享你使用列表的经历，欢迎留言交流哦~

参考资料：

1. IBM Style Guide
2. Google Developer Documentation Style Guide: https://developers.google.cn/style

你可能想读：

技术文档诞生记 | 完整的技术写作流程是怎样的？

GitHub + Markdown 的新轻型技术写作模式速览

GitHub + Markdown 的深度技术写作实践解析

Technical Writer 不只是写产品说明书的

Lilian Lee：技术文档种类详解 | Technical Writer 可提供的交付物有哪些？

不同阶段如何应对 Technical Writer 的职业顾虑或烦恼？

Technical Writer 日常工作中好用的小工具

技术传播人士应该知道的色彩搭配常识

如何使用颜色来提高技术文档的可读性？

技术翻译需要有 Technical Writer 的 sense

深度解析关于技术翻译的六个认知误区

如何让你的内容输出更加专业更有设计感？

Technical Writer 如何 Review 技术文档？

书单 | 有哪些技术传播从业者必知必看的书籍？

有哪些适合技术传播从业者关注的优质博客？（一）

有哪些适合技术传播从业者关注的优质博客？（二）

经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（上篇）

经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（下篇）

技术传播沙龙精彩分享 | 高校老师与行业大牛谈“互联网技术写作”

英语技术文档的标题到底该大写还是小写？

如何使用正则表达式批量添加和删除字符？

英语技术文档中如何正确使用时态？

英语技术文档中如何正确使用人称？

Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言

如何为 Markdown 文件自动生成目录？

技术写作实例解析 | 简洁即是美

两分钟趣味解读 Technical Writer

若脱离理解，直译得再正确又有何意？

优质译文不应止于正确，还要 Well-Organized

Technical Writer 需要 Technical 到会写代码吗？

写在入职技术型创业公司 PingCAP 一个月之后

揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记

-END-