Lists and table

好的列表可以将混乱的技术文档变得有序。通常技术文档读者都喜欢列表。因此，写作时，请寻找机会将散乱的文字变成列表。

正确地选择列表

技术文档中的列表主要有以下三种形式：

• 项目符号列表（bulleted list）
• 数字列表（numbered list）
• 内嵌列表（embedded list）

对未排序的项目使用项目符号列表，对有序项目使用有序列表。换句话说：

• 对项目符号列表的项目做重排，列表的意义不会变化。
• 对数字列表的项目做重拍，则会修改列表的意义。

例如，如下列表是项目符号列表，重排列表的顺序并不会改变列表的意义：

Bash provides the following string manipulation mechanisms:

• deleting a substring from the start of a string
• reading an entire file into one string variable

反之，下面这个列表必须是有序列表，如果改变其项目的顺序，该列表的意义也会变化：

Take the following steps to reconfigure the server:

1. Stop the server.
2. Edit the configuration file.
3. Restart the server.

内嵌列表（有时也称为run-in list）的项目直接写在句子里。下面这个例句中有一个包含4个项目的内嵌列表:

The llamacatcher API enables callers to create and query llamas, analyze alpacas, delete vicugnas, and track dromedaries.

一般来说，内嵌列表是呈现技术信息的一种很糟糕的方式。应当将内嵌列表转化为项目符号列表或数字列表。例如，上述例句应该转换为如下段落：

The llamacatcher API enables callers to do the following:

• Create and query llamas.
• Analyze alpacas.
• Delete vicugnas.
• Track dromedaries.

练习

将下列段落转换为1个或多个列表：

Today at work, I have to code three unit tests, write a design document, and review Janet's latest document. After work, I have to wash my car without using any water and then dry it without using any towels.

不要忘记介绍你的列表。

保持列表项平行

有效列表和有缺陷列表的区别是什么？有效列表的表项是平行的，而缺陷列表项是不平行的。平行的列表中，列表项看起来就应该摆在一起。也就是说，所有的列表项在以下方面都是一致的：

• 语法
• 逻辑范畴
• 大小写
• 标点符号

反之，非平行的列表，在以上方面至少有一方面是不满足的。

例如，如下列表是平行列表。这是因为其所有列表项都是复数名词（语法）、可食用（逻辑分类）、小写（大小写）且没有句号或者逗号（标点符号）。

• carrots
• potatoes
• cabbages

相反，如下列表在上述四项属性上并不一致:

• carrots
• potatoes
• The summer light obscures all memories of winter.

如下列表中，所有项目都是完整的句子，有着句子应该有的大小写和标点符号。因此该列表是平行列表：

• Carrots contain lots of Vitamin A.
• Potatoes taste delicious.
• Cabbages provide oodles of Vitamin K.

列表第一项的形式，决定了读者想要在后续项目看到的形式。

练习

如下列表是平行的还是非平行的？

• Broccoli inspires feelings of love or hate.
• Potatoes taste delicious.
• Cabbages.

如下列表是平行的还是非平行的？

• The red dots represent sick trees.
• Immature trees are represented by the blue dots.
• The green dots represent healthy trees.

有序列表项使用祈使动词起头

有序列表项应该使用祈使动词起头。就像open或者 start一样，祈使动词是命令。请看如下例句中，所有的列表项如何以祈使动词开头:

1. Download the Frambus app from Google Play or iTunes.
2. Configure the Frambus app's settings.
3. Start the Frambus app.

如下有序列表不是平行列表，因为只有前两句以祈使动词开头：

1. Instantiate the Froobus class.
2. Invoke the Froobus.Salmonella() method.
3. The process stalls.

练习

将如下列表改为平行列表，确保所有的列表项都以祈使动词开头：

1. Stop Frambus
2. The key configuration file is /etc/frambus. Open this file with an ASCII text editor.
3. In this file, you will see a parameter named Carambola, which is currently set to the default value (32). Change this value to 64.
4. When you are finished setting this parameter, save and close the configuration file
5. now, start Frambus again.

表项中合理使用标点

如果列表项是句子，那么请按照句子规范使用标点和大小写。反之则不然。例如，如下列表项是一个句子，所以我们将Most的M大写，并在句末加上句号：

• Most carambolas have five ridges.

然而，如下列表项并非句子，所以the中的t无需大写，且无需使用句号：

• the color of lemons

创建有用表格

分析性思维热爱表格。给定一个包含多个段落和一个表格的页面，工程师的眼睛会聚焦在表格上。

创建表格请考虑以下准则：

• 选择有意义的列标题，不要让读者自己猜测每一列的内容。
• 避免在单元格内放入过多文本。如果单元格内有多于两个句子，请问问自己是否这些信息应该以其他形式存在。
• 尽管不同列可以包含不同类型的数据，但也请尽量保证每列内容的并行性。例如，某一列的单元格不能既有数据信息也有著名的马戏团演员。

![Note]

不是所有的表格都能很好地做到自适应。例如，有的表格在笔记本上能完美呈现，但是在手机上却看起来糟糕透了。

介绍每个列表和表格

我们建议你使用一句话来介绍每个列表和表格，告诉读者这个列表和表格呈现的是什么内容。即，给出列表或表格的上下文。同时，使用冒号而不是句号为介绍性句子结尾。

虽非必须，我们还是建议你可以在介绍句中加入单词following，就像如下例句：

The following list identifies key performance parameters:

Take the following steps to install the Frambus package:

The following table summarizes our product's features against our key competitors' features:

练习

为如下表格写一个介绍句：

Reference

原文：https://developers.google.com/tech-writing/one/lists-and-tables