上一篇讲 GitHub 上有哪些地方可以练英语。这一篇更靠前一步：你打开一份英文文档，得先知道它是哪一种。
用错读法，读什么都费劲。用对读法，很多文档你其实只需要读三分钟。
一、先说结论
技术文档不是"一种东西"。它至少有四种基本类型，每一种的写作目的不同，所以结构不同，读法也必须不同。
这个分类不是我编的，来自一个叫 Diátaxis 的文档框架（现在被 Django、Cloudflare、Ubuntu、Gatsby 等一大批项目采用）。它的分法很干净——两个维度切成四块：
| 偏学习（要懂） | 偏工作（要用） | |
|---|---|---|
| 偏行动（动手） | Tutorial 教程 | How-to 指南 |
| 偏认知（理解） | Explanation 解释 | Reference 参考 |
四个格子，四种文档。认出来是哪一格，读法立刻就不一样了。
二、Tutorial（教程）：唯一一种必须老实照着做的
怎么认
- 标题常带
Getting Started、Your First ___、Quickstart、Tutorial - 有编号步骤，一步一条命令
- 有预期的输出贴在下面
- 几乎不解释"为什么"
怎么读
不要读，直接做。
教程是唯一一种"读完再动手"会浪费时间的文档。因为它的设计前提是：你什么都不知道，所以它把每一步都替你决定了。
你做的时候只关心两件事：
- 报错了吗
- 输出和它写的一样吗
不一样，就是你的第一个真实问题——这时你已经得到了一个可以拿去问的素材。
一个提醒
教程的目的是让你建立信心，不是让你学会。它故意回避了所有边界情况、所有配置选项、所有"如果你的环境不一样怎么办"。
所以：跑通教程 ≠ 会用这个项目。 很多人卡在这一步——教程跑通了，真要写自己的东西就懵了。
三、How-to（指南）：直接跳到你需要的那一节
怎么认
- 标题是任务式的：
How to configure HTTPS、Deploying to Kubernetes、Migrating from v1 - 没有编号步骤的强连续性，每节独立
- 步骤里会带前提条件（“假设你已经……"）
怎么读
只读你当前要解决的那一节，前面的全跳过。
How-to 的写法是"问题导向"的，作者已经假设你有具体目标。你从头读到尾，会读到一堆你不需要的操作。
读的时候只看三个东西：
- 前提条件（Prerequisites）—— 你有没有
- 命令本身
- “Note” / “Warning” / “Caveat” 标记的段落 —— 这是作者踩过坑之后加进去的，价值最高
最容易忽略的一行
How-to 里经常有一句：
This will overwrite your existing configuration.
一句话，五个词。不看，数据就没了。 这类警告句在英文文档里通常很短、很平、很容易滑过去——恰恰是最该停下来读的。
四、Reference（参考）：不读，只查
怎么认
- 表格、列表、参数说明
- 标题是名词短语：
API Reference、Configuration Options、CLI Commands - 结构高度规律，重复度高
怎么读
不要通读。永远不要通读。
Reference 是字典。没人会从头读字典。
用法是：先知道"它有什么”，再在需要时查。
所以你要做的是先扫一遍目录/侧边栏，建立一张心理地图：
“哦，这个库有
Client、Session、Auth、Errors四个部分。”
这张地图比记住任何具体参数都重要。 有了它，你不知道具体怎么写的时候，至少知道该去哪里找。
读一条参数的顺序
一条典型的参数说明长这样：
timeout (float, optional): Maximum seconds to wait before
aborting the request. Defaults to 30. Set to None to disable.
Raises TimeoutError if exceeded.
信息密度最高的读法是倒着读：
Raises TimeoutError if exceeded—— 出错会怎样（先看后果）Defaults to 30—— 默认值是多少（不改会怎样）Set to None to disable—— 特殊情况怎么办（边界）Maximum seconds to wait—— 它到底是什么（最后看定义）
为什么倒着读？ 因为"它是什么"你已经从名字猜到了（timeout 还能是什么），而后三条是你猜不到的。
五、Explanation（解释）：唯一一种值得"整篇读完"的
怎么认
- 标题常带
Understanding、Why、Architecture、Design、Concepts、How ___ works - 有大段散文，几乎没有代码
- 会讲历史、讲取舍、讲"为什么不那样做"
怎么读
这一类要慢读，而且值得读完。
因为 Explanation 不解决任何具体问题——它改变的是你对整件事的理解模型。
判断要不要读的标准很简单：
“我能不能用一句话说清它是怎么工作的？”
不能 → 读 Explanation。 能 → 不用读，去干活。
这类文档的隐藏价值
Explanation 里最值钱的部分，往往是那些**“为什么不用 X 方案”**的段落。
作者写这一段时，通常是他真的试过 X 方案并失败了。这是你没花时间就捡到的经验——比任何正面介绍都有用。
六、四种文体之外，还有五种你天天遇到
Diátaxis 覆盖的是"项目自己的文档"。但实际上你还会碰到这五种，各有各的读法：
1. README
混合体。前三分之一是营销（跳过），中间是教程（照做），后面是指南（按需）。
2. RFC / 规范文档
这是最容易读错的一类。
RFC 里每个句子都在做规定，不在描述。关键在情态动词，而且它们有严格定义（来自 RFC 2119）：
| 词 | 强度 | 含义 |
|---|---|---|
| MUST / SHALL | 绝对 | 必须，否则不合规 |
| MUST NOT | 绝对 | 禁止 |
| SHOULD | 强建议 | 有正当理由可以不做，但要想清楚 |
| SHOULD NOT | 强建议 | 同上，反向 |
| MAY / OPTIONAL | 可选 | 做不做都合规 |
读 RFC 时只做一件事：把 MUST 和 SHOULD 分清楚。
一个协议实现里，MUST 是红线，SHOULD 是可以商量的。混了这两者，写出来的东西在互操作性上会出问题。
3. API 文档
Reference 的变体，但多一个关键信息：示例请求 + 示例响应。
读 API 文档，先看示例，再看参数表。 一个完整的 curl 调用比十行参数说明更快建立直觉。
4. Release Notes / CHANGELOG
只读三块：
- Breaking Changes —— 永远是第一优先
- Security —— 有就立刻看
- Deprecations —— 现在不坏，但将来会坏
Feature 列表可以扫一眼，其他全跳过。
判断标准：这次升级会不会让我的代码坏掉？——只看会不会坏。
5. 源码注释
最容易忽略、信息密度最高的一类。
好的注释不是在说"这行代码做了什么"（代码自己能说），而是在说：
- 为什么这么写（
// needed because the API returns null on empty） - 什么情况下会出问题（
// TODO: this breaks if name contains a slash） - 什么东西不能动（
// DO NOT reorder, order matters here）
读源码时，先扫注释，再读代码。 注释是作者留下的路标。
七、一个二十秒的判断流程
打开一份陌生文档，二十秒内问自己三个问题：
1. 它有没有编号步骤？
有 → 教程（照做）或指南（跳到需要那节）
没有 → 继续问
2. 它是表格/列表/参数为主吗？
是 → 参考（别通读，建地图，按需查）
不是 → 继续问
3. 它主要是在讲"为什么"吗？
是 → 解释（慢读，值得读完）
不是 → 大概是个混合体，按段落判断
这一个流程能省掉你 80% 的无效阅读。
八、三句实话
第一，绝大多数人把 Reference 当 Explanation 读，所以永远读不完。 参数表不是用来通读的，是用来查的。建立目录地图，比记住任何一条参数都值。
第二，教程跑通之后，你会产生一种"我会了"的错觉。 破法是：关掉教程，从零自己写一遍。 写不出来，说明你只是跟着执行，没有理解。
第三，读文档的能力，本质是"提问的能力"。 你不是在读它说了什么，你是在找它有没有回答你正在问的那个问题。带着问题读，比任何技巧都有效。
这是我的个人整理。Diátaxis 框架由 Daniele Procida 提出，公开可查；RFC 2119 的情态动词表是 IETF 的正式规范。文中的判断流程是我的用法，不是原文。
这个系列的其他几篇
- GitHub 是最好的英语老师：从读 Issue 到能开口 —— 从哪儿练
- 读不懂一句技术英语时，真正该查的不是单词 —— 句子怎么拆
- 在 PR 里把话说清楚：一来一回的完整样本 —— 怎么写
- 技术人的口语：不追求流利，追求说对 —— 怎么说
- 计算机英语高频术语对照表 —— 随时查