自我学习框架笔记
What → Why → How 增强版
这不是一套"怎么写"的模板，而是一套"怎么学"的方法论。
你按照这个结构去研究任何一个新技术，研究完，博客也就写完了。
学习和写作是一件事，不是两件。
目录
- 金字塔总览
- 阶段〇：选种子——在动笔之前
- 第一章：What —— 建立心智模型
- 第二章：Why —— 建立价值判断
- 第三章：How —— 建立实操能力
- 第四章：When / Which —— 建立决策框架
- 第五章：Where Next —— 建立学习路径
- 写作自查清单
- 常见反模式
- 附录：范例对照
金字塔总览
┌──────────────────────────────────────────┐ │ 一句话核心结论（标题即论点） │ │ "Kubernetes 是容器编排的事实标准， │ │ 但小团队用它可能是过度设计" │ └──────────────────────────────────────────┘ │ ┌─────────────┬─────────────┬─────┴─────┬─────────────┐ ▼ ▼ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ What │ │ Why │ │ How │ │When/Which│ │ Where │ │ 是什么 │ │ 为什么 │ │ 怎么做 │ │ 怎么选 │ │ Next │ │ │ │ │ │ │ │ │ │ 怎么进阶 │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │定义 │ │痛点 │ │最小体验 │ │场景矩阵 │ │进阶路线 │ │心智模型 │ │历史 │ │核心API │ │竞品对比 │ │相关技术 │ │类比锚点 │ │设计哲学 │ │实战案例 │ │迁移策略 │ │资源推荐 │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘读前须知
每一章都包含三个部分：
| 部分 | 作用 |
|---|---|
| 这一章要回答什么问题 | 你的目标——读者读完这段应该能回答这些问题 |
| 怎么写（含模板） | 具体的写作指导 + 可直接套用的结构 |
| 常见错误 | 这一章最容易踩的坑 |
阶段〇：选种子——在动笔之前
在开始 What/Why/How 之前，先做两个决定。
1. 确定"一句话核心结论"
你的整篇文章，最终要传达的一个观点是什么？它不应该是中性的介绍，而应该有一个立场。
| 弱标题（无立场） | 强标题（有立场） |
|---|---|
| “WebAssembly 入门指南” | “WebAssembly 不是 JavaScript 的替代品——它是 JavaScript 的搭档” |
| “Rust 语言介绍” | “Rust 的学习曲线很陡，但只有前 20% 是必须爬的” |
| “了解 GraphQL” | “REST API 没坏的时候，别急着修——GraphQL 的真实适用场景” |
操作：动笔前，用一句话写出你的核心论点。如果写不出来，说明你对这个技术的理解还不够深，先去研究。
2. 明确目标读者
不要试图写给"所有人"。选择一个具体的人：
- “一个用 REST 写了三年 API 的后端开发，听说 GraphQL 很久但没试过”
- “一个在创业公司用 Python 做数据分析的人，想了解 Rust 能不能加速关键路径”
读者的技术背景决定了你的类比锚点、代码示例的语言、以及可以跳过的基础知识。
第一章：What —— 建立心智模型
这一章要回答什么问题
读完这一章，读者应该能回答：
- 这个东西到底是什么？（一句话定义，不是一段话）
- 它在整个技术版图里的位置是什么？（它和哪些东西相邻？）
- 它的核心概念有几个？之间的关系是什么？
- 我能用已知的知识怎么理解它？
怎么写
1.1 一句话定义（必须）
用不超过 50 个字定义这个技术。如果做不到，说明你还没理解透。
模板： ______ 是一个 ______，它通过 ______ 解决了 ______ 问题。 例子： WebAssembly 是一个浏览器内的低级字节码格式，它通过提供接近原生的执行速度， 解决了 JavaScript 在计算密集型场景下性能不足的问题。1.2 概念地图（强烈推荐）
不要用文字罗列概念，画一张图展示核心概念之间的关系。人的大脑通过关系记忆，不是通过列表。
示例：WebAssembly 概念地图 ┌──────────────────────────────────────────────────┐ │ 浏览器 │ │ ┌─────────────┐ ┌──────────────────────┐ │ │ │ JavaScript │ ◄──► │ WebAssembly (WASM) │ │ │ │ 引擎 │ 互操作 │ .wasm 字节码 │ │ │ │ (JS glue) │ │ 线性内存 │ │ │ └─────────────┘ └──────────┬───────────┘ │ │ │ │ │ 编译自 ↓ │ │ ┌──────┼──────┐ │ │ │ C/C++│ Rust │ ... │ │ └──────┴──────┘ │ └──────────────────────────────────────────────────┘1.3 类比锚点（必须）
找一个读者已经知道的东西做类比。好的类比不是"完全准确"，而是建立正确的第一印象。
模板： 如果说 ______ 是 ______，那 ______ 就是 ______。 例子： 如果说 JavaScript 是解释执行的脚本（像一个现场翻译官）， 那 WebAssembly 就是提前编译好的字节码（像一个已经翻译好、印刷出来的手册）。 类比边界（诚实声明）： - 相似点：都比纯解释快 - 不同点：WASM 不能直接访问 DOM，手册不能自己翻页类比边界很重要——告诉读者这个类比哪里不对，防止他们产生错误的认知。这说明你真正理解了。
1.4 最小认知模型（可选但推荐）
用一段代码或一个极简示例，让读者看到这个东西长什么样。不需要完整，只需要直观。
;; 不需要理解每个指令，只需要"感受"它长什么样 (module (func $add (param i32 i32) (result i32) local.get 0 local.get 1 i32.add ) (export "add" (func $add)) )这一章的常见错误
| 错误 | 为什么错 | 怎么改 |
|---|---|---|
| 用 Wikipedia 式定义开头 | 太学术，读了等于没读 | 用"你遇到了什么问题 → 这个东西怎么解决"的方式开头 |
| 概念罗列而不讲关系 | 读者记不住孤立的定义 | 画概念关系图，讲清楚 A 和 B 的区别与联系 |
| 类比太牵强或没有类比边界 | 误导读者 | 加一句"这个类比哪里不对" |
| 一开始就深入实现细节 | 读者还没建立心智模型 | 把源码分析留给第三章 |
第二章：Why —— 建立价值判断
这一章要回答什么问题
读完这一章，读者应该能回答：
- 这个技术解决了什么真实痛点？（没它之前有多痛？）
- 为什么是现在？（为什么之前没人做 / 做不成？）
- 它的设计哲学是什么？（它背后的"价值观"是什么？）
- 它是必需品还是可选品？
怎么写
2.1 Before / After 对比（必须）
这是最有说服力的写法。展示一个具体场景，没有这个技术前怎么解决，有了之后怎么解决。
模板： 场景：______ Before（没有 XX 的时候）： ┌────────────────────────────────────────────┐ │ （描述痛苦的解决方案，最好有代码或数据） │ │ │ │ 问题1：______ │ │ 问题2：______ │ │ 问题3：______ │ └────────────────────────────────────────────┘ After（有了 XX 之后）： ┌────────────────────────────────────────────┐ │ （描述新的解决方案） │ │ │ │ 改善1：______（量化！） │ │ 改善2：______ │ └────────────────────────────────────────────┘关键：Before 场景必须是读者亲身经历过的痛点。如果读者不觉得痛，Why 就站不住。
2.2 技术演进时间线（可选）
解释"为什么是现在"——展示这个技术出现的历史条件。
例子：WebAssembly 为什么是 2015 年出现的？ 2010 Emscripten 出现（C/C++ → asm.js） │ 证明了"在浏览器里跑 C 代码"是可行的，但性能不够 │ 2013 asm.js 规范发布 │ 浏览器厂商开始优化，性能提升 2-4 倍 │ 2015 WebAssembly 社区组成立 │ Mozilla/Google/Microsoft/Apple 共同推进 ▼ 关键洞察：与其优化 JS 引擎跑 asm.js，不如定义一个新的二进制格式2.3 设计哲学（强烈推荐）
每个技术都有其"价值观"——设计者做取舍的原则。理解设计哲学，你就理解了为什么 API 长这样、为什么某些功能缺失。
模板： 这个技术的设计哲学可以归纳为 N 条原则： 1. ______ 优先于 ______ 举例：______ 2. ______ 优先于 ______ 举例：______ 例子（Go 语言）： 1. 简洁优先于 clever → 没有泛型（直到 Go 1.18），因为简洁比表达力更重要 2. 显式优先于隐式 → 没有隐式类型转换，所有错误都要显式处理 3. 编译速度优先于极致优化 → 编译快如解释型语言，即使生成的二进制不是最快的2.4 不是银弹（必须）
这一节不能省略。明确说出这个技术不适合什么场景。这比说它适合什么更有价值，因为：
- 体现你真的用过，不是纸上谈兵
- 帮助读者避免错误选型
- 让你的文章在搜索引擎中差异化（别人都在吹，只有你在说"别乱用"）
模板： 这个技术不适合以下场景： 1. ______ → 你应该用 ______ 代替 2. ______ → 你应该用 ______ 代替 3. ______ → 你应该用 ______ 代替这一章的常见错误
| 错误 | 为什么错 | 怎么改 |
|---|---|---|
| 只讲优点不讲局限性 | 显得像营销软文，不可信 | 必须写"不适用的场景" |
| Before/After 太抽象 | 读者感受不到痛苦 | 用具体的代码、截图、数据 |
| 堆砌性能数据而不讲设计哲学 | 数据会过时，思想不会 | 先讲哲学，再给数据佐证 |
| 把"大家都用"当理由 | 从众不是论据 | 找到技术决策的因果链 |
第三章：How —— 建立实操能力
这一章要回答什么问题
读完这一章，读者应该能回答：
- 我能在5 分钟内跑起来吗？（Hello World 级别）
- 最常用的20% 功能怎么用？（覆盖 80% 场景）
- 有一个完整的、接近真实场景的例子可以参考吗？
- 有哪些坑？哪些最佳实践？
怎么写
3.1 5 分钟跑起来（必须）
读者的耐心只有 5 分钟。如果 5 分钟内跑不起来，他们会关掉页面。
要求： 1. 从零开始（假设读者只有一台装了操作系统的电脑） 2. 每一步都可复制粘贴 3. 每一步都有预期输出（"你应该看到..."） 4. 每一步都有失败处理（"如果报 X 错误，检查 Y"）不要直接贴完整项目的代码。要从npm init/cargo new开始，一步步构建。
3.2 核心 API / 概念的实际用法（必须）
按使用频率排序，而不是按文档顺序。先讲每天都会用到的，再讲偶尔用到的。
模板：核心功能清单 | 优先级 | 功能 | 使用频率 | 一句话说明 | |--------|------|---------|-----------| | ★★★ | X | 每天 | _________ | | ★★★ | Y | 每天 | _________ | | ★★☆ | Z | 每周 | _________ | | ★☆☆ | W | 偶尔 | _________ | 然后对每个 ★★★ 功能，给出： - 最简示例（3-5 行代码） - 一个容易犯的错误 - 一句最佳实践3.3 一个端到端实战案例（强烈推荐）
一个贯穿全章的完整例子，从需求到代码到部署。这个例子应该：
- 接近真实场景（不是 TODO App，虽然 TODO App 可以用来说明基础概念）
- 有业务逻辑（不是 CRUD）
- 能跑通（你在写文章时自己跑过）
案例结构： 1. 场景描述：我们要做一个 ______ 2. 架构设计：（一张图） 3. Step 1: ______ → 代码 + 解释 4. Step 2: ______ → 代码 + 解释 5. Step 3: ______ → 代码 + 解释 6. 完整代码：GitHub 链接3.4 踩坑记录 / 常见问题（强烈推荐）
这是读者在搜索引擎里搜索的内容，也是他们真正会反复回来看的内容。
模板：常见问题 Q1: ______ 报错怎么办？ 原因：______ 解决：______ Q2: ______ 性能很差怎么办？ 原因：______ 解决：______ Q3: 从 ______ 迁移过来，______ 对应什么？ 回答：______这一章的常见错误
| 错误 | 为什么错 | 怎么改 |
|---|---|---|
| 按官方文档顺序讲 API | 读者不是来背字典的 | 按使用频率排序，先讲高频 |
| 代码块没有上下文 | 读者不知道这段代码放在哪里 | 每个代码块注明文件名 |
| 只给成功路径 | 读者按你的步骤做，遇到报错就放弃 | 预判常见错误，给出解决方案 |
| 示例太简单或太复杂 | TODO App 太无聊，企业级项目太庞大 | 选一个"30 分钟能跟着写完"的场景 |
第四章：When / Which —— 建立决策框架
这一章要回答什么问题
读完这一章，读者应该能回答：
- 我的情况适合用这个技术吗？
- 我的情况不适合的话，应该用什么？
- 如果我在用旧方案，怎么迁移？
- 如果我要选型，怎么对比？
怎么写
4.1 决策矩阵（必须）
用表格帮助读者做决策。不要只是列功能，要列"什么时候选这个"。
模板：技术选型决策表 | 场景 | 推荐方案 | 理由 | |------|---------|------| | 你的团队 < 5 人，项目 < 1 万行 | A 方案 | 简单优先 | | 你的团队 > 20 人，微服务架构 | B 方案 | 类型安全 + 代码生成 | | 你需要最大性能，不在乎开发速度 | C 方案 | 无运行时开销 | | 你需要快速原型验证 | A 方案 | 最少代码量 |4.2 竞品对比（可选但推荐）
对比不是为了说谁好谁坏，而是帮读者理解设计权衡。
对比原则： 1. 不要只列功能清单（X 有，Y 没有）——太浅了 2. 要对比设计哲学的差异导致的不同选择 3. 诚实描述自己的偏好和理由 模板： | 维度 | A | B | C | |------|---|---|---| | 设计哲学 | 显式优于隐式 | 约定优于配置 | 性能优于一切 | | 学习曲线 | 陡（2周入门） | 缓（2天入门） | 中（1周入门） | | 适合团队 | 大团队 | 小团队/个人 | 性能敏感 | | 不适合 | 快速原型 | 大规模项目 | 业务逻辑复杂 | | 我的选择 | 大项目用 A | 小项目用 B | 核心链路用 C | 注意：每个维度都要写"为什么"，不是只打勾。4.3 迁移策略（如果适用）
如果你的目标读者正在使用旧方案，告诉他们怎么迁移。
模板：从 X 迁移到 Y Step 1: 双写阶段（风险最低） - 新旧方案并行运行 - 验证新方案的输出和旧方案一致 - 耗时预估：______ Step 2: 灰度切流 - 10% → 50% → 100% - 每一步的观察指标：______ - 回滚条件：______ Step 3: 清理旧方案 - 可以删除的代码：______ - 必须保留的数据：______这一章的常见错误
| 错误 | 为什么错 | 怎么改 |
|---|---|---|
| 只说"看情况" | 等于没说 | 给出具体的 if-else 决策逻辑 |
| 竞品对比写成攻击 | 显得不专业 | 说"A 优先选择了 X，因此牺牲了 Y"而非"A 的 Y 不行" |
| 没有说"你不应该用"的场景 | 误导读者 | 明确列出反场景 |
第五章：Where Next —— 建立学习路径
这一章要回答什么问题
读完这一章，读者应该能回答：
- 学完这个，我下一步该学什么？
- 有哪些进阶话题值得深入了解？
- 有哪些优质资源（不是罗列链接，是告诉你每个链接有什么用）？
怎么写
5.1 学习路线图
模板：学习路径 入门（本文覆盖）→ 进阶 → 精通 ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ 入门 │ │ 进阶 │ │ 精通 │ │ (本文) │───▶│ │───▶│ │ │ │ │ 性能调优 │ │ 源码贡献 │ │ 核心概念 │ │ 高级模式 │ │ 定制实现 │ │ 基础用法 │ │ 生产部署 │ │ 架构决策 │ └─────────────┘ └─────────────┘ └─────────────┘ 1-2周 1-3个月 6个月+5.2 资源推荐（带注释）
不要只贴链接。每个资源都要说明为什么推荐、什么时候看。
模板： | 资源 | 类型 | 适合阶段 | 推荐理由 | |------|------|---------|---------| | 官方文档的 Quick Start | 文档 | 入门 | 最好的 Hello World，但 API 参考部分不适合通读 | | 《XX 实战》第 3-5 章 | 书籍 | 入门后 | 用一个完整项目串联核心概念，比官方文档有上下文 | | XX 项目的 GitHub Issues | 社区 | 进阶 | 看别人的踩坑记录，比看博客管用 | | XX Conf 2024 的 Y 演讲 | 视频 | 进阶 | 讲了内部实现原理，理解原理后 API 就不需要背了 |写作自查清单
写完初稿后，逐项检查：
结构层面
- 文章有一个明确的核心论点（不只是"介绍 X"）
- 标题包含了立场或独特角度
- 五个章节（What/Why/How/When/Next）都有，但篇幅不必均等
- 每个章节开头有一个"读完能回答什么问题"的引导
What 层面
- 能用一句话说清这个东西是什么
- 有概念关系图（不是概念列表）
- 有读者熟悉的类比，且说明了类比边界
- 没有过早深入实现细节
Why 层面
- 有具体的 Before/After 对比
- Before 场景是读者亲身经历过的痛点
- 有"不适合的场景"（不是银弹声明）
- 讲了设计哲学，不只是性能数据
How 层面
- 5 分钟内可以跑起来
- 每个代码块标注了文件名
- 预判了常见错误并给出解决方案
- 有一个端到端的实战案例
When 层面
- 有决策矩阵（不是功能对比表）
- 明确说了什么时候不该用
- 竞品对比是在解释设计取舍，不是在打分
Next 层面
- 有学习路线图
- 推荐的每个资源都有理由
语言层面
- 能用"你"不用"我们"（更亲切）
- 能用短句不用长句
- 每个概念第一次出现时给了简短定义
- 代码块的注释是中文（解释为什么），代码本身是英文
常见反模式
🚫 反模式 1：教科书目录式
❌ 目录： 1. 概述 2. 安装 3. API 参考 4. 配置项 5. 示例 ✅ 目录： 1. What：一句话 + 一张心智模型图 2. Why：一个痛点场景 + 设计哲学 3. How：5 分钟跑起来 → 核心用法 → 踩坑记录 4. When：决策矩阵 + 竞品对比 5. Next：学习路线 + 资源推荐🚫 反模式 2：API 字典式
不要把博客写成 API 文档。API 文档是查的，博客是理解的。如果你发现自己在大段列举函数签名，停下来，问自己：读者真正需要理解的是什么？
❌ "该模块提供了 15 个 API，分别是 getX()、setX()、listX()..." ✅ "该模块的核心思想是 CRUD 模型，你只需要理解 3 个核心操作： get/set/list，其余的 12 个都是它们的变体。"🚫 反模式 3：没有立场
❌ "X 和 Y 都是优秀的工具，各有优劣，具体选哪个看情况。" ✅ "如果你的团队少于 5 人，选 X；如果你在构建大规模微服务，选 Y。 我个人的经验是：大部分项目高估了自己需要的复杂度， 所以我建议从 X 开始，等真正遇到瓶颈再考虑 Y。"读者读你的文章，是要借你的判断力。你没有立场，文章就没有价值。
🚫 反模式 4：代码块轰炸
连续的代码块会让读者迷失。每个代码块前后都要有：
- 前：这段代码要做什么？为什么这样写？
- 后：这段代码的关键点是什么？（1-2 句即可）
❌ ```python def process(data): ...defanalyze(data):...defreport(data):...✅
先定义数据处理函数——核心思路是用 pipeline 模式串联三个步骤：
defprocess(data):...关键点：validate()必须在transform()之前调用，否则会漏掉无效数据。
接下来是分析步骤…
### 🚫 反模式 5：试图覆盖所有人❌ “本文适合初学者，也适合有经验的开发者，也适合架构师…”
✅ “本文假设你有一年以上的 Web 开发经验，了解基本的 HTTP 协议。
如果你是完全零基础，建议先看 MDN 的 Web 开发入门指南。”
--- ## 附录：范例对照 以 "WebAssembly 入门" 为例，展示弱版 vs 强版的开头： ### ❌ 弱版开头 > WebAssembly（简称 WASM）是一种低级的字节码格式，由 W3C 社区组于 2015 年首次发布。它是一种可移植的二进制指令格式，可以作为高级语言的编译目标。本文将介绍 WebAssembly 的基本概念、使用方法以及生态系统。 **问题**：Wikipedia 风格，没有立场，没有痛点，读者不知道为什么要读。 ### ✅ 强版开头 > 你在浏览器里跑过一个图像处理算法吗？当 10MB 的图片需要实时滤镜时，JavaScript 会卡到用户想关掉页面。 > > WebAssembly 就是来解决这个问题的——它让你把 C/Rust 写的代码编译成浏览器能直接运行的字节码，速度接近原生。 > > 但 WebAssembly 不是 JavaScript 的替代品。它不能操作 DOM，不能直接访问 Web API。它更像是 JavaScript 请来的"外援"—— > JS 负责 UI 交互，WASM 负责计算密集的部分。 > > 这篇文章会帮你建立这个心智模型，然后用一个真实的图像处理案例，让你体验从"写 Rust"到"在浏览器里跑"的完整流程。 **为什么更好**：场景 → 定义 → 立场 → 预期管理。读者第一段就知道这篇文章对他们有没有用。 --- ## 最后的话 这个框架是你学习新技术的 **SOP**，也是你写博客的**脚手架**。 当你接触一个新技术的流程：- 选种子 → 确认核心论点和目标读者
- 读官方 Overview → 填 What 部分（一句话定义、概念地图、类比锚点）
- 读官方 Motivation / 对比文档 → 填 Why 部分（痛点、设计哲学）
- 跑 Quick Start + 做一个小项目 → 填 How 部分（记录踩坑）
- 横向对比竞品 → 填 When 部分（写决策矩阵）
- 梳理知识盲区 → 填 Next 部分（规划自己的进阶路径）
当你写完一篇文章，你不仅帮助了读者，你自己也完成了从"听说过"到"能解释清楚"的跨越。 **教，是最好的学。**