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. How5 分钟跑起来 → 核心用法 → 踩坑记录 4. When决策矩阵 竞品对比 5. Next学习路线 资源推荐 反模式 2API 字典式不要把博客写成 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 部分规划自己的进阶路径当你写完一篇文章你不仅帮助了读者你自己也完成了从听说过到能解释清楚的跨越。 **教是最好的学。**