列表

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

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

无序列表和有序列表

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

【无序列表示例】

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

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

【有序列表示例】

解决办法：

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

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

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

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

列表的使用

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

使用列表的规范 错误案例 正确案例
1. 并列列表项中建议使用相似的句子结构。 SQL 查询优化器：
- 支持 eager aggregate
- 更详细的 explain 信息
- union 算子并行化
- 子查询性能优化
- 优化 CBO 框架		 SQL 查询优化器：
- 支持 eager aggregate
- 支持更详细的 explain 信息
- 支持 union 算子并行化
- 优化了子查询性能
- 优化了 CBO 框架
2. 每一项的长度要尽量接近。 在 GitHub 上提交的新 Issue 分为以下几种：
- 如果您发现了 bug 需要报告
- 请求开发一项新功能
- 常规问题
- 为解决或提升性能提的 Issue		 在 GitHub 上提交的新 Issue 分为以下几种：
- 错误报告
- 功能请求
- 常规问题
- 性能问题
3. 避免在每一项开头重复相同的词语。 TiDB 与 MySQL 安全特性的差异：
- 不支持外部身份验证方式。
- 不支持列级别权限设置。
- 不支持使用证书验证身份。		 相较于 MySQL 安全特性，TiDB 不支持的功能有如下几种：
- 外部身份验证方式
- 列级别权限设置
- 证书验证身份方式
4. 使用清晰的、描述性的句子或短语来引出列表。 状态可以通过 store 的 state_name 来确定：
- Up：这个 store 正常服务
- Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断
- Down：超过一小时没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本		 你可以通过 store 的 state_name 确定其状态：
- Up：这个 store 正常服务
- Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断
- Down：超过一小时没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本
5. 并列列表项中保持标点符号一致。
若列表项是句子，那么每一项建议以句号结尾；
若列表项是词组，则不建议以任何标点结尾；
若列表项既有词组又有句子，则建议统一以句号结尾。		 【例一】TiDB Binlog 支持以下功能场景：
- 数据同步。
- 实时备份和恢复。

【例二】指定数据源的相关信息：
- 在 Name 处，为数据源指定一个名称。
- 在 Type 处，选择 Prometheus。
- 在 URL 处，指定 Prometheus 的 IP 地址。
- 其他字段		 【例一】TiDB Binlog 支持以下功能场景：
- 数据同步
- 实时备份和恢复

【例二】指定数据源的相关信息：
- 在 Name 处，为数据源指定一个名称。
- 在 Type 处，选择 Prometheus。
- 在 URL 处，指定 Prometheus 的 IP 地址。
- 其他字段。
6. 不要滥用无序列表，否则会导致它们失去应有的效果。 无 无
7. 避免嵌套使用列表，这样通常会显得冗长复杂。 如果一定要表现多层级的列表，建议最多不超过 3 级，且每一级都要用不同样式的小圆点。 无 无
8. 一个操作任务的步骤描述通常要使用有序列表，为方便用户记忆，建议严格限制列表项在 7 个以下，最多不要超过 9 个步骤。 无 无