## 列表

当有 3 项或更多重要信息需要展示时，纵向列表是最清晰且吸引眼球的方式。但如果项目少于 3 项且无需特别强调，将其直接放在句子中通常效果更好。

也可以创建多级嵌套列表，在某一级别下另起一行，缩进**四个空格**即可开始更低级别的列表。

### 无序列表和有序列表

技术文档中的列表分为有序列表 (ordered list) 和无序列表 (unordered list) 两种。一般而言，**当列表项之间的顺序不重要时，使用无序列表；当各项之间的顺序很重要时，使用有序列表。**

【无序列表示例】

目前，TiDB 数据库使用了以下组件：

- Prometheus Server：用于收集和存储时间序列数据。
- Client 代码库：用于定制程序中需要的 Metric。
- Alertmanager：用于实现报警机制。

【有序列表示例】

解决办法：

1. 编辑数据源文件。
2. 手动创建所有的表。
3. 设置参数跳过检查。

有序列表的使用场景较少。当列表项的内容是以下几种时，应该使用有序列表。

- 必须按顺序操作的步骤（最常用）
- 需要进行排名的多项内容
- 需要在下文进行引用的规则或其它信息（比如下文需要引用该列表的第 3 项时可以说“规则 3”）

**【重要原则】除非顺序很重要，否则不建议使用有序列表。**

### 列表的使用

技术文档中使用列表建议遵循以下规范。

| 使用列表的规范           | 错误案例               | 正确案例                  |
| ------------------ | -------------------------- | -------------------------- |
| 1. 并列列表项中建议使用相似的句子结构。    | SQL 查询优化器：  <br>   - 支持 eager aggregate <br> - 更详细的 explain 信息 <br> - union 算子并行化 <br> - 子查询性能优化 <br> - 优化 CBO 框架 | SQL 查询优化器：  <br>   - 支持 eager aggregate <br> - 支持更详细的 explain 信息 <br> - 支持 union 算子并行化 <br> - 优化了子查询性能 <br> - 优化了 CBO 框架 |
| 2. 每一项的长度要尽量接近。   | 在 GitHub 上提交的新 Issue 分为以下几种：  <br>   - 如果您发现了 bug 需要报告 <br> - 请求开发一项新功能 <br> - 常规问题 <br> - 为解决或提升性能提的 Issue | 在 GitHub 上提交的新 Issue 分为以下几种：  <br>   - 错误报告 <br> - 功能请求 <br> - 常规问题 <br> - 性能问题 | 
| 3. 避免在每一项开头重复相同的词语。 | TiDB 与 MySQL 安全特性的差异： <br>  - 不支持外部身份验证方式。 <br> - 不支持列级别权限设置。 <br> - 不支持使用证书验证身份。 | 相较于 MySQL 安全特性，TiDB 不支持的功能有如下几种：  <br>   - 外部身份验证方式 <br> - 列级别权限设置 <br> - 证书验证身份方式 |
| 4. 使用清晰的、描述性的句子或短语来引出列表。  | 状态可以通过 store 的 state_name 来确定：  <br>   - Up：这个 store 正常服务 <br> - Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断 <br> - Down：超过一小时没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本 | 你可以通过 store 的 state_name 确定其状态：  <br>   - Up：这个 store 正常服务 <br> - Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断 <br> - Down：超过一小时没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本 |
| 5. 并列列表项中保持标点符号一致。  <br> 若列表项是句子，那么每一项建议以句号结尾；  <br>   若列表项是词组，则不建议以任何标点结尾； <br> 若列表项既有词组又有句子，则建议统一以句号结尾。 | 【例一】TiDB Binlog 支持以下功能场景： <br>  - 数据同步。 <br>  - 实时备份和恢复。 <br> <br> 【例二】指定数据源的相关信息： <br> - 在 Name 处，为数据源指定一个名称。<br> - 在 Type 处，选择 Prometheus。 <br>  - 在 URL 处，指定 Prometheus 的 IP 地址。 <br> - 其他字段 | 【例一】TiDB Binlog 支持以下功能场景： <br>  - 数据同步 <br>  - 实时备份和恢复 <br> <br> 【例二】指定数据源的相关信息： <br> - 在 Name 处，为数据源指定一个名称。<br> - 在 Type 处，选择 Prometheus。 <br>  - 在 URL 处，指定 Prometheus 的 IP 地址。 <br> - 其他字段。  |
| 6. 不要滥用无序列表，否则会导致它们失去应有的效果。          | 无                | 无               |
| 7. 避免嵌套使用列表，这样通常会显得冗长复杂。     如果一定要表现多层级的列表，建议最多不超过 3 级，且每一级都要用不同样式的小圆点。 | 无           | 无                     |
| 8. 一个操作任务的步骤描述通常要使用有序列表，为方便用户记忆，建议严格限制列表项在 7 个以下，最多不要超过 9 个步骤。 | 无                       | 无                         |