信息表达：把内容写清楚，让读者用得上
“query_timeout：超时时间，默认 30。”这句话格式没有问题，但读者仍不知道单位、0 的含义和修改影响谁。信息表达要解决的，就是这些会妨碍判断和操作的问题。
本页先讨论内容缺口，再比较标签页、折叠和表格。例子中的 query_timeout 是虚构参数，用于演示写法，不是 MySQL 配置建议。
从内容到发布，分别检查什么
| 当前问题 | 去哪里看 |
|---|---|
| 格式能否表达合并表格或共享片段？ | 标记语言对照 |
| 背景、步骤和参数混在了一起？ | 概念说明、操作步骤、参数参考 |
| 编辑器里正常，发布后变了样？ | 发布工具与扩展语法 |
这几类内容可以按需查阅。同一事实可以出现在不同文档里，但组织方式应围绕读者当前的问题。
从读者疑问找缺口
| 读者会问什么 | 需要确认的事实 |
|---|---|
| 限制等待时间，还是执行时间？ | 控制对象、计时起止点 |
| 30 是秒还是毫秒？ | 单位、类型、取值范围 |
| 0 是不等待，还是不限制？ | 特殊值含义 |
| 改完影响谁？ | 作用域与生效时机 |
| 超时之后发生什么？ | 错误、事务与连接的后续状态 |
先查对应版本的说明、源码或测试结果，再改写。找不到依据的行为列为待确认，不用肯定的语气填补空白。
query_timeout 限制单次查询的执行时间，单位为秒，默认值为 30。接受 0～3600 的整数，0 表示不设置时限。
修改只影响当前会话之后发起的查询，正在执行的查询不受影响。达到时限时，当前查询终止并返回 QUERY_TIMEOUT。
事务是否回滚、连接是否可继续使用，以及如何查询当前值，仍需核实。
写得更具体，不等于事实已经正确。把未确认的部分留出来，是这段说明的重要组成部分。
按读者做事的顺序安排
通常先说条件与影响，再写操作，最后说明怎样确认结果。风险提醒放在有关动作之前；只有少数人需要的原理或历史放在附近的补充说明里。
标题说明目标，段首先给结论，链接名称直接写出目标内容。任务很短时，可以在几句话中完成，不必套一套长模板。
标签页：同一任务的不同写法
读者通常只需要一种语言或平台时，可以用标签页。共同的前置条件放在外面，里面只放各自的内容。
- JSON
- YAML
{
"query_timeout": 30
}
query_timeout: 30
需要同时比较时，用并排展示或表格更方便。有先后依赖的步骤应保持连续，不能分散到不同标签里。本例把选项写入 URL，便于分享指定写法；站内搜索、键盘操作和打印效果仍需另外检查。
折叠：收起补充信息，保留关键条件
如果读者不展开折叠块也能完成任务，里面通常适合放原理、历史或少见的排错细节。必须知道的前置条件、风险和验证方法保持可见。
修改只影响当前会话之后发起的查询。
为什么不只写“立即生效”？
“立即”没有说明影响范围。读者可能以为正在执行的查询也会改变。写清对象和时间边界，比换一个更强烈的副词有用。
折叠标题直接写出问题。整页内容都要逐个展开时，先考虑是否应该拆页或精简。
表格：按内容分配列宽
表格适合比较同类信息。默认值通常很短，说明文字较长，均分列宽可能导致不必要的折行。
左右滑动表格，查看完整三列。
| 参数 | 默认值 | 说明 |
|---|---|---|
query_timeout | 30 | 单位为秒。限制单次查询的执行时间；0 表示不设置时限。修改只影响当前会话之后发起的查询。 |
max_result_rows | 1000 | 限制一次返回的结果行数。结果达到上限时，需要缩小查询范围，不能据此判断源表只有这些行。 |
trace_query_execution | false | 记录当前会话的查询执行信息。记录可在当前会话的诊断页查看，会话关闭后清除。 |
这里使用 27% / 14% / 59% 作为对照，并不是通用比例。窄屏下保留横向滚动，不截掉说明。
先删无用列，再分配宽度；长步骤移到表外。窄屏保留完整内容，在表格区域内滚动。表头应使用真正的表头单元格，不能只靠加粗或颜色区分。
列宽示例用了什么？
本例使用 HTML colgroup 和 table-layout: fixed，外层允许横向滚动。具体比例需要按内容试读，而不是套一个固定数值。
需要跨行跨列时，可对照合并单元格示例。
其他内容适合怎样展示
| 读者要做什么 | 可以采用 | 需要避免 |
|---|---|---|
| 按顺序完成操作 | 有序步骤 | 漏掉条件、预期结果 |
| 按条件选择路径 | 判断表、流程图 | 分支没有结果 |
| 复制配置 | 代码块 | 输入与输出混在一起 |
| 理解调用关系 | 图加文字说明 | 箭头含义不明 |
| 找到界面控件 | 标注截图加菜单路径 | 只有截图，没有可搜索的名称 |
| 注意限制 | 就近的提醒 | 每一段都用警告框 |
用真实任务检查效果
请一位不熟悉内容的人找出适用版本、判断参数能否设为 0，并找到验证方法。观察他在哪里停住：条件藏得太深，术语没解释，还是两个地方的说明不一致？
这类观察能指向具体修改。浏览量、停留时间和点击率只能提供线索，不能单独证明文档是否解决了问题。
作者自查清单
下面是我整理的检查问题，不是行业评分标准。按文档类型选用，可以标记“不适用”；勾选只记录你的判断，不会自动验证技术事实。
按当前文档选用
记录已核实的事项，不给文档打分。
已确认 0 项 · 待检查 12 项 · 不适用 0 项。记录仅保留在当前页面。
哪些检查适合自动化
构建失败、内部链接缺失和固定术语写法适合交给工具。技术结论是否成立、读者能否完成任务，还需要审阅和实际验证。
用规则提醒需要复核的措辞
例如可以用 Vale 提醒作者检查“立即生效”。它只能找到词语，不能判断上下文已经解释清楚，更不能推断数据库行为。
在专门的演练目录创建 .vale.ini：
StylesPath = styles
MinAlertLevel = warning
[*.md]
BasedOnStyles = Review
在 styles/Review/Scope.yml 中保存规则：
extends: existence
message: "请核对 '%s' 是否交代了作用域和生效时机。"
level: warning
nonword: true
tokens:
- 立即生效
- 马上生效
安装 Vale 后运行 vale example.md。这里使用警告让作者复核，不因命中某个词就判定内容错误。中文词组的边界设置见 Vale existence 规则。
中文审校也可评估 DocSifter。工具的提示和 AI 建议都应结合上下文处理。
一个可以放进本站的构建检查
以下示例适用于本仓库的 package.json、锁文件和 check:docs-links 脚本。新项目需要换成自己的版本和命令。它构建站点并检查生成后的文档内链；不包含产品行为验证或公网部署。
name: Documentation checks
on:
pull_request:
paths:
- 'docs/**'
- 'i18n/**'
- 'src/**'
- 'static/**'
- 'scripts/**'
- 'package.json'
- 'pnpm-lock.yaml'
- 'docusaurus.config.ts'
- 'sidebars.ts'
- '.github/workflows/docs-checks.yml'
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 9.15.4
- uses: actions/setup-node@v4
with:
node-version: '22'
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm build
- run: pnpm check:docs-links
这是可采用的工作流示例，是否将它设为合并必需条件，需要在实际仓库里配置并验证。不要把“能构建”当成“所有内容正确”。
继续阅读：操作说明的完整小例子、参数参考或发布工具的取舍。