Day 199 图解 — 技术写作

本目录只放图解，不生成图片文件。所有图都能在 GitHub / 本地 Markdown 渲染器中直接显示。

图 1：一篇文章的三个退出层

flowchart TD
    A[标题 + 首段] -->|30 秒| B{和我有关吗}
    B -->|否| X[关掉页面]
    B -->|是| C[小标题 + 表格]
    C -->|3 分钟| D{结论能用吗}
    D -->|否| X
    D -->|是| E[实验手册 + 代码]
    E -->|30 分钟| F[照着重现]
    F -->|成功| G[信任 + 引用]
    F -->|失败| H[反馈给作者]
    H --> I[作者补环境/命令]
    I --> E

读法：任何一层都要自洽。只读第二层的人也应该拿走可用结论—— 这就是"实验手册"必须独立成章、而不是散在叙述里的原因。

图 2：断言的三级与证据要求

flowchart LR
    S[一句话] --> Q{是事实吗}
    Q -->|是| F[给出处或一行验证]
    Q -->|否| R{是推断吗}
    R -->|是| I[写推理链 + 至少一次测量]
    R -->|否| O[观点: 说清立场, 不伪装成事实]
    F --> OK[可发布]
    I --> OK
    O --> OK

"显然"之所以危险，是因为它让第三类句子（观点）冒充第一类（事实），跳过了举证。

图 3：可复现性契约的五个字段

                 +-----------------------------+
                 |      一次可复现的实验        |
                 +-----------------------------+
                    |      |      |      |    |
        +-----------+      |      |      |    +-------------+
        |                  |      |      |                  |
   +---------+      +-----------+  |  +-----------+   +-------------+
   |  环境    |      |   命令     |  |  |  样本量    |   |  输出指纹    |
   | 版本/CPU |      | 可复制一行 |  |  | N 次/中位  |   |  sha256     |
   +---------+      +-----------+  |  +-----------+   +-------------+
                                   |
                            +-------------+
                            |  原始输出    |
                            | stdout/stderr|
                            +-------------+

缺任意一格，读者就只能"相信"，不能"验证"。

图 4：Markdown 体检器的状态机

stateDiagram-v2
    [*] --> Text
    Text --> Code: 遇到代码围栏
    Code --> Text: 遇到代码围栏
    Text: 普通文本态
    Text: 解析标题/列表/表格
    Code: 代码块态
    Code: 原样收集, 不解析
    note right of Code
        围栏内的 # 是注释, 不是标题
        漏掉这条规则 = 体检器变噪音源
    end note

图 5：从实验到发布的流水线

flowchart LR
    A[真机实验] -->|抓 stdout/环境/哈希| B[可复现卡片]
    B --> C[写作: 结论先行]
    C --> D{体检 >= 90?}
    D -->|否| E[修结构/补条件]
    E --> D
    D -->|是| F[静态站构建]
    F --> G[HTTP 200 验证]
    G --> H[发布]
    H --> I[读者复现]
    I -->|失败| A

注意最后一条回边：发布不是终点，读者复现失败才是最有价值的输入。

图 6：误报是怎么被修掉的（真实数据）

版本                        post.md 评分   误报
v1  逐词匹配                 79/100        7 条（front matter + 引用 + TODO 清单）
v2  剥离「」引号              85/100        2 条（ASCII 双引号没剥）
v3  剥离 ASCII 引号           100/100       0 条
v4  行内代码也剥离 + 收紧词表   100/100       0 条（README 自检 94 -> 100）

结论：规则的价值不在"抓得多"，而在"只抓该抓的"。一条会对自己开火的规则， 在真实使用中会迅速被忽略。