# 参数参考：把读者需要查的事实写全

Source: https://flowingdocs.com/docs/information-design/reference/

参考说明服务于带着具体问题来查找的读者：这个值是什么单位，能不能设为 0，改完影响谁？这里以参数说明为例，介绍需要核实哪些事实，以及怎样让它们容易找到。

## 让一个词条能独立被理解 {#definition}

读者可能从搜索直接进入某个参数，不会从第一页读起。参数名、简短定义、适用版本和关键限制应出现在词条附近。不要要求读者先读完整本手册才知道单位。

## 用问题检查字段是否齐全 {#zero-ambiguity}

| 读者的问题         | 应核实的信息               |
| ------------- | -------------------- |
| 控制什么？         | 对象、触发条件和计时起止点        |
| 值怎么写？         | 类型、单位、取值范围           |
| 0、负数或空值是什么意思？ | 特殊值是否允许及其含义          |
| 影响谁？          | 全局、会话或其他作用域，以及继承关系   |
| 什么时候生效？       | 修改方式、重启要求、对正在执行操作的影响 |
| 默认值与建议值一样吗？   | 对应版本的默认值；建议另写适用条件    |
| 输入不合法会怎样？     | 报错、拒绝、截断或自动调整        |
| 怎么确认？         | 查询当前值或操作状态的方法        |

不适用的字段可以注明“不适用”。尚未核实的行为不能用猜测补成确定事实；应先向研发确认、查阅对应版本资料或执行测试。

## 对照两种写法 {#sandbox}

下面是**虚构服务**的参数示例，用来比较说明中缺少什么。参数名、范围和行为都是教学设定，不是 MySQL 的配置建议。

## 表格要方便查找 {#table-typography}

参数名和值较短，说明通常较长，可以适当增加说明列的宽度。具体比例取决于内容和屏幕，不需要统一规定为某个百分比。可在[列宽演示](https://flowingdocs.com/docs/information-design/#tables)中比较。

标签能提示作用域或重启要求，但也要有文字；长命令、操作步骤和排错过程应链接到单独说明。窄屏下保留完整内容，通过表格区域滚动查看。

## 一个可复用的词条结构 {#template}

继续使用虚构的 `query_timeout`，避免把写作样板误当成真实数据库参数。


<strong>阅读效果</strong>


### query\_timeout

限制单次查询的执行时间，从查询开始执行时计时。

| 属性    | 说明                        |
| ----- | ------------------------- |
| 类型和单位 | 整数，秒                      |
| 默认值   | 30                        |
| 范围    | 0～3600                    |
| 特殊值   | 0 表示不设置时限                 |
| 作用域   | 当前会话                      |
| 生效方式  | 影响修改后发起的查询，正在执行的查询不受影响    |
| 超时结果  | 当前查询终止，返回 `QUERY_TIMEOUT` |

**还需要核实的行为**：事务是否回滚、连接是否继续可用，以及如何查询当前设置。未确认这些问题之前，这个词条还不能作为真实产品的完整操作依据。


<strong>复制结构</strong>


```markdown
### 参数名

一句话说明控制对象；标明产品版本。

| 属性 | 已核实的值或行为 |
| --- | --- |
| 类型和单位 | … |
| 默认值和范围 | … |
| 特殊值 | … |
| 作用域 | … |
| 生效方式 | … |
| 异常结果 | … |

#### 验证
给出查询命令或界面位置，以及预期结果。

#### 建议与限制
写明建议适用的环境和依据；尚未核实的项目列为待确认。
```

真实参数需要查对应版本。例如 [MySQL 8.0 缓冲池调整说明](https://dev.mysql.com/doc/refman/8.0/en/innodb-buffer-pool-resize.html)交代了分块约束、调整阶段与状态监测。不能据此为所有实例补上固定的 TPS 波动比例，也不能把一个默认值直接当成生产推荐值。

## 发布前自查 {#checklist}

- 同一参数的单位、类型和示例是否一致？
- 默认值是否标明版本？建议是否说明条件？
- 会话值与全局值、当前值与持久化配置是否区分？
- 特殊值、异常行为和验证方法是否有依据？
- 缺少的信息是否真正核实，而非写得更肯定？

接下来可以用[自查清单](https://flowingdocs.com/docs/information-design/#scorecard)检查一篇现有文档，或查看[操作步骤怎样编排](https://flowingdocs.com/docs/information-design/task/)。