参数参考：把读者需要查的事实写全
参考说明服务于带着具体问题来查找的读者：这个值是什么单位，能不能设为 0，改完影响谁？这里以参数说明为例，介绍需要核实哪些事实，以及怎样让它们容易找到。
让一个词条能独立被理解
读者可能从搜索直接进入某个参数，不会从第一页读起。参数名、简短定义、适用版本和关键限制应出现在词条附近。不要要求读者先读完整本手册才知道单位。
用问题检查字段是否齐全
| 读者的问题 | 应核实的信息 |
|---|---|
| 控制什么？ | 对象、触发条件和计时起止点 |
| 值怎么写？ | 类型、单位、取值范围 |
| 0、负数或空值是什么意思？ | 特殊值是否允许及其含义 |
| 影响谁？ | 全局、会话或其他作用域，以及继承关系 |
| 什么时候生效？ | 修改方式、重启要求、对正在执行操作的影响 |
| 默认值与建议值一样吗？ | 对应版本的默认值；建议另写适用条件 |
| 输入不合法会怎样？ | 报错、拒绝、截断或自动调整 |
| 怎么确认？ | 查询当前值或操作状态的方法 |
不适用的字段可以注明“不适用”。尚未核实的行为不能用猜测补成确定事实；应先向研发确认、查阅对应版本资料或执行测试。
对照两种写法
下面是虚构服务的参数示例，用来比较说明中缺少什么。参数名、范围和行为都是教学设定，不是 MySQL 的配置建议。
缺了哪些事实？
虚构参数，仅用于写作练习；不是 MySQL 参数表。
query_timeout超时时间，默认 30，立即生效。
先想一想：这句话是否足以支持读者操作？再切换到“补齐后”。
表格要方便查找
参数名和值较短，说明通常较长，可以适当增加说明列的宽度。具体比例取决于内容和屏幕，不需要统一规定为某个百分比。可在列宽演示中比较。
标签能提示作用域或重启要求，但也要有文字；长命令、操作步骤和排错过程应链接到单独说明。窄屏下保留完整内容，通过表格区域滚动查看。
一个可复用的词条结构
继续使用虚构的 query_timeout，避免把写作样板误当成真实数据库参数。
- 阅读效果
- 复制结构
query_timeout
限制单次查询的执行时间，从查询开始执行时计时。
| 属性 | 说明 |
|---|---|
| 类型和单位 | 整数，秒 |
| 默认值 | 30 |
| 范围 | 0～3600 |
| 特殊值 | 0 表示不设置时限 |
| 作用域 | 当前会话 |
| 生效方式 | 影响修改后发起的查询，正在执行的查询不受影响 |
| 超时结果 | 当前查询终止，返回 QUERY_TIMEOUT |
还需要核实的行为：事务是否回滚、连接是否继续可用，以及如何查询当前设置。未确认这些问题之前，这个词条还不能作为真实产品的完整操作依据。
### 参数名
一句话说明控制对象；标明产品版本。
| 属性 | 已核实的值或行为 |
| --- | --- |
| 类型和单位 | … |
| 默认值和范围 | … |
| 特殊值 | … |
| 作用域 | … |
| 生效方式 | … |
| 异常结果 | … |
#### 验证
给出查询命令或界面位置，以及预期结果。
#### 建议与限制
写明建议适用的环境和依据；尚未核实的项目列为待确认。
真实参数需要查对应版本。例如 MySQL 8.0 缓冲池调整说明交代了分块约束、调整阶段与状态监测。不能据此为所有实例补上固定的 TPS 波动比例，也不能把一个默认值直接当成生产推荐值。
发布前自查
- 同一参数的单位、类型和示例是否一致？
- 默认值是否标明版本？建议是否说明条件？
- 会话值与全局值、当前值与持久化配置是否区分？
- 特殊值、异常行为和验证方法是否有依据？
- 缺少的信息是否真正核实，而非写得更肯定？