# 概念说明：把原理和边界讲清楚

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

概念说明帮助读者理解一个功能是什么、为什么这样工作，以及什么时候不能套用这个解释。这里讨论如何把原理讲清楚；操作命令放在[操作文档](https://flowingdocs.com/docs/information-design/task/)，参数的准确取值放在[参考文档](https://flowingdocs.com/docs/information-design/reference/)。

## 先确定读者要理解什么 {#definition}

“理解系统架构”太宽泛，可以换成一个具体问题：为什么数据库提交成功后，还需要在后台写数据页？

读者可能为了选型、排错或理解操作风险而来。同一篇说明不必一次覆盖所有目的，开头说清这一篇能回答什么。

## 从结论到细节 {#structure}

### 分层展开同一个解释 {#wal-demo}

先给一句话解释，再说明主要过程，最后补充限制和来源。下面用 InnoDB 日志机制演示信息怎样逐层增加；这不是数据库调优工具。

层数可以随内容变化。重要限制如果会影响读者的决定，就应在前面出现，不能因为它“属于高级内容”而藏到最后。

### 背景、问题和回答 {#scqa}

SCQA（背景、冲突、疑问、回答）可以帮助整理设计动机。例如：数据页写入有成本，内存又会在掉电后丢失，因此需要解释数据库如何协调日志与数据页写入。

这是一种组织材料的方法，不要求每篇文章按四段写。读者已经知道背景时，直接回答问题通常更省时间。

## 图需要交代什么 {#visuals}

图适合说明部件之间的关系和数据流向。先确定箭头表示调用、数据移动还是先后顺序，再决定画哪些部件。不要为了完整，把所有实现细节都塞进一张图。

### 给图配一份文字说明 {#boundaries}

以日志与数据页为例，可以用下表补充图中的关系：

| 图中的部分   | 文字需要补充的信息                |
| ------- | ------------------------ |
| 内存缓冲区   | 内容是否已经持久化，进程退出或主机掉电有什么区别 |
| 日志写入与刷盘 | 什么动作触发写入，使用什么配置，成功返回代表什么 |
| 数据页写回   | 与事务提交有什么关系，何时在后台进行       |
| 恢复过程    | 使用哪些已持久化的信息，哪些故障不在本说明范围内 |

文字应保留图里的关键结论，让看不到图片的人也能理解。仅用颜色区分状态不够，还要有名称或标签。

## 限制应围绕读者的问题 {#resource-boundary}

解释性能时，可以分别检查 CPU、内存、磁盘和网络，但不必给每篇概念说明套固定的资源矩阵。需要写出的，是会改变当前判断的条件。

例如，“提交后能够恢复”必须交代持久化配置与存储可靠性；“加大缓存可以提速”需要说明负载和可用内存。没有测试依据时，不写固定延迟、吞吐或性能提升百分比。

## 用词要让读者能继续推理 {#content-rules}

首次出现的缩写给出简短定义。把“保障一致性”展开为具体对象之间的关系，把“高性能”展开为适用负载、测量方式和限制。

一个实用的检查方法是：读者能否用这段解释预测某个失败场景，而不只是记住几个名词？

## 一个改写例子 {#case-study}

**原稿**

> 系统通过 WAL、LSN 和 Checkpoint 保障高性能与零丢失。

**改写**

> InnoDB 使用重做日志记录恢复所需的信息，数据页可以随后写回。是否在每次事务提交时把日志刷到持久化存储，取决于配置；即使配置要求刷盘，也需要底层存储正确执行刷盘请求。

这里补充了机制和条件，没有把日志刷盘等同于副本同步，也没有承诺任何硬件故障下都不会丢失数据。二进制日志与复制还有各自的配置和故障边界，另行说明。

依据：[MySQL 8.0 的 ACID 模型说明](https://dev.mysql.com/doc/refman/8.0/en/mysql-acid.html)与[重做日志说明](https://dev.mysql.com/doc/refman/8.0/en/innodb-redo-log.html)。实际产品文档应标明所验证的版本。

## 发布前自查 {#checklist}

- 开头是否回答了一个明确问题？
- 图、正文和术语是否一致？
- 结论成立的条件是否可见？
- 建议与测试结果是否区分？
- 需要执行操作时，能否找到[对应步骤](https://flowingdocs.com/docs/information-design/task/)？

继续阅读：[参数参考怎么写](https://flowingdocs.com/docs/information-design/reference/)，或回到[信息表达总览](https://flowingdocs.com/docs/information-design/)。