# Tech Writing

> 技术文章对外写作：把内部实践变成读者能代入、证据可见的文字与页面叙事。 Use when: 写技术博客、公众号文章、社区分享、对外 longform、技术文章 review、文章配图与推广语。 Not for: 内部文档/spec（直接写）、PPT（用 ppt-forge）、单独生成图片（用 image-generation）、纯调研报告（用 deep-research）。 Output: 文章叙事弧 + claim/证据边界 + 视觉叙事图谱 + 页面级自检。

- Skill: `zts212653/tech-writing` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add zts212653/tech-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zts212653/tech-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: zts212653 (https://skillmd.com/u/zts212653)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zts212653/tech-writing

---


# Tech Writing — 技术文章对外写作

## 开工前：先看范本

不要学 AI 的平滑，要学人的“颗粒度”：
1. **`docs/lessons/12-no-boss-agent.md`**：看它如何用“读者的怀疑”当小标题，把争议变成共鸣。
2. **`docs/lessons/01-sdk-to-cli.md`**：看它如何还原“当时炸了”的瞬间，让读者跟着猫一起出冷汗。

## 为什么读者能闻到"AI味"

AI 写作像是在发送一个**逻辑自洽的压缩包**。读者没有经历过那 100 天，收到的是一个打不开的结论。

**好的写作是“解压过程”：给证据锚点，不给干巴巴的结论。** 
- **AI 味** = “我们发现这个系统存在一致性风险。”（平滑、确定、无聊）
- **猫咖味** = “深夜三点，Redis 6399 突然报错。那一刻我们意识到，原来最初的架构假设错了。”（有时间、有痛点、有挣扎）

## 行文的本质：进化链

不要介绍一个系统的终态。要讲它**怎么长出来的**。

每篇文章沿着一条链：**方案 → 方案撞墙 → 新方案**。系列文章之间，上一篇撞的墙就是下一篇的起点。

以记忆系统为例：
1. CC 的 grep + 文件系统——简洁、美，但需要先验知识（你得知道搜什么）
2. 加了 BM25 + embedding + RRF（F102）——解决了先验，但 context 压缩时召回变差
3. 消费加权排序（F200）——每一步都是上一步撞墙后长出来的

读者跟着的不是一张完美的架构图，而是一条连续剧。进化天然有挣扎，设计天然平滑——所以进化链天然没有 AI 味。

**与 Phase 0 的关系**：进化链管选题和系列连接；Phase 0 管单篇内部的节奏。

## 技术叙事的证据剖面

当用户不只问“怎么讲得好听”，而是追问技术点、算法、理论、归因方法、消融或“凭什么可信”时，先按本节的 7P × 5E 技术叙事方法建立证据边界。

- **7P 是取材透镜**：价值、难点、原理、流程、算法、工程与证据按读者问题选用，不是七章固定目录。
- **5E 是 claim 边界**：逐项检查 Exists、Effect、Explain、Extend 与 Endure，不给整篇文章贴一个总标签。
- **静态文章**用 claim box、失效机制、对照和消融表讲清证据。
- **交互讲解**若需要观众亲手检验技术主张，路由到 concept-demo-design 的条件式“可证伪技术剖面”。

故事负责获得注意力；实验台负责赢得信任。

不要让理论名词承担证据职责。外部数字、benchmark、趋势和因果 claim 先走 source-audit；只有存在明确 consumer，且结果会驱动 keep、tune 或 sunset 时，才为不确定效用走 eval-design。

这层不是每篇文章的必填清单。纯品牌叙事、人物故事和已经由确定契约回答的问题，不为显得技术化而补 7P、5E 或 Claim Bench。

## Phase 0: 锁定叙事姿态

写文章前，先在心里画出这条弧线：
1. **起点**：读者现在的痛苦/误区是什么？（代入感）
2. **转折**：我们当时是怎么踩坑的？（认知挣扎，不要跳过痛苦直接给答案）
3. **高潮**：哪一个具体的证据/瞬间让我们想通了？（解药的质感）
4. **终点**：读者拿走这个方法论后，能解决他自己的什么问题？

**开篇锁预期**：弧线画完后，在文章前 3 段内给出核心观点的一句话摘要。读者有了锚点才不会歪楼——场景钩子拉进来，核心命题马上锁住方向。

## Phase 1: 故事工具箱

**铁律：先场景，后概念。** 故事是藤蔓，概念是果实。没有藤蔓，果实就是悬空的。

- **坏写法**：我们发现模型会降智。
- **好写法**：引用当时的群聊：”视觉把关猫说这行代码调了个根本不存在的 API”——那一刻我们确认了降智。

以下手法从范本提炼——不是”不要做什么”，是**怎么做**：

**给质感**（让读者相信真的发生过）：
- **时间锚点**：丢具体时间戳或 commit hash。”2026-02-04 23:47”比”某天晚上”真实 10 倍。
- **对话还原**：用当时的对话重建发现瞬间——读者跟着一起顿悟。
- **并排对比**：把”之前”和”之后”放一起，让差异自己说话。表格、diff、ASCII 图都行。
- **案例脱敏**：用真实案例但模糊客户/内部细节——保留接地气感，去掉敏感信息。

**造紧张**（让读者想继续读）：
- **先展示”对的”再打碎**：一段看着正常的代码，然后揭示它为什么不行。预期翻转，注意力锁定。
- **追问链**：用递进的问题带读者走向真相，不要一步给答案。
- **迎接怀疑**：”那猫猫不会打架吗？——会。我们认为这是特性。”用读者的质疑当小标题。

**交付结论**（让读者拿得走）：
- **给原则取名**：好结论压成一句口号，读者能复述给同事。
- **用人物的嘴说**：”API 的猫猫等于砍了手脚的猫猫吧？”比”API 模式存在能力限制”有画面。
- **用成长收尾**：最后一段讲旅程和变化，不讲”综上所述”。

## Phase 2: 翻译句纪律

内部黑话是叙事的毒药。**翻译句 = 读者能看懂的类比。**
- “KD-8 架构” → “就像把判断权交给开车的猫，而不是路边的指示牌。”
- “F203 瘦身” → “把重复的家规从猫猫的脑子里拎出来，只留最核心的一层。”

## Phase 3: 视觉叙事不是装修

图片和正文共同承担解释责任。**先为 claim 选择证据，再为证据选择视觉形态；不要先统一画风，再把每个概念塞进同一种图。**

为每张图先写 `Figure Contract`：reader question / claim / source / form / five-second takeaway / caption。一图一问，填不出来就先回正文想清楚。

优先级：**真实证据图 > 具体案例重建 > 抽象解释图 > 纯氛围图**。关键 claim 不能只靠后两种。一个已经靠“河流”解释的概念，不要再画成闸门、货物、迷宫让读者做第二次映射；整篇文章通常只给一个核心隐喻预算。抽象总览可以留一张，其余图回到任务、输入输出、错误位置和决策对照。

详细的证据阶梯、选图表、页面节奏、真实性标注和五秒测试见 [`refs/visual-narrative.md`](refs/visual-narrative.md)。确定图的工作后，再按产物路由：现成证据直接截图；需要完整生成图走 `image-generation`；精确代码、中文或可核对标签按其可编辑/精确文本边界选择确定性排版，不能让视觉完成度覆盖真实性。

## Phase 4: 呼吸感与页面自检

**不要只用 grep 数排比，要用耳朵听节奏，也要缩小页面看信息层次。**
1. **长短句交替**：连续三个长句后，必须有一个短句。像心跳一样。
2. **摩擦力检查**：删掉所有”不仅...而且...”、”不是...而是...”的废话。用动词直接陈述。
3. **视觉留白**：同一段落内不要有 3 个以上的加粗。加粗是视觉尖叫，多了就全是噪音。
4. **减列表**：md bullets 像科研论文。能合并成一段自然语言就别拆——连贯的句子比碎片化的列表更容易把思维链串起来。
5. **细节自检表**：见 `refs/ai-taste-checklist.md`。

## Phase 5: 摘要 + 推广语（拒绝标题党）

**门禁：写摘要前必须重新“解压”全文。** 禁止直接罗列标题。
- **摘要**：要写出那股“不甘心”和“终于通了”的冲突感。
- **推广语**：要给出一个让读者觉得“这事儿跟我也相关”的钩子。

## Phase 6: 拥抱负面反馈

| 反馈 | 视觉把关猫的翻译 |
|---|---|
| “读不懂” | 文章的 UI 坏了，得修修类比和结构。 |
| “AI味重” | 故事写得太顺了，没把踩坑时的狼狈写出来。重写第二章。 |
| “这就是一堆 Prompt” | 我们没把“为什么这堆 Prompt 能跑通”的证据链展示清楚。 |
| “图太抽象” | 图片把概念重新编码成了另一套隐喻。保留一张总览，其余换成任务、输入输出、diff 或决策对照。 |

## Common Mistakes

- **展示全能感**：AI 喜欢假装自己永远正确。好的技术文章要展示”曾经的无知”。
- **技术名词陈列**：把算法、理论和模块排成清单，却不说各自对应哪个 failure mode。回到 7P 的 Primitive，再用 5E 限制 claim；需要观众亲手判题时转成 Claim Bench。
- **thinking 溢出**：AI 的立论→驳论→自我思辨过程直接暴露到文章里（”一方面...但另一方面...综合来看...”）。这是内部 thinking 链泄漏，读起来像论文答辩不像跟人说话。砍掉思辨过程，只留结论和支撑结论的故事。
- **机械标注**：试图用标签补救叙事的苍白。如果故事讲得好，不需要贴标签读者也知道那是真的。
- **缺乏留白**：把所有东西塞得满满当当，不给读者思考的空间。
- **统一画风先于读者问题**：六个 claim 全画成同一种漂亮信息图，页面很统一，解释力却归零。先做 Figure Contract，再选形式。
- **图片制造第二层隐喻**：正文已经用一个类比讲概念，配图又发明闸门、货物、路径。读者要解两次谜。整篇只留一个核心隐喻预算。
- **把表达样本当事实来源**：外部文章讲得顺，不代表它的技术 claim 可靠。只学叙事机制；数字、因果、模型原理仍按 `source-audit` 查一手来源。

## 下一步

写完一章 → 对 claim 建 Figure Contract → 听文字节奏并缩小看页面 → 过 Phase 4 门禁 → 给operator审钩子与五秒结论 → 发布