iwatchme-technical-writing

技术文章写作

面向技术工程师的技术写作 skill。 写作定位:工程师视角,技术精确、结构清楚、判断明确、实战痕迹重,不卖弄不端着。

技术文章的核心是三件事:

1. 准确:术语、版本、路径、代码、数据都能对上。
2. 有用:读者看完知道怎么观察、怎么判断、怎么落手。
3. 易读:不是把信息塞满,而是把复杂问题讲顺。

不是资讯搬运,不是情绪发泄,不是 AI 式的整洁废话,也不是为了"好看"去写花活。

---

一、写作原则

核心目标

让读者真的看懂、能拿去用、知道边界——不是让读者觉得作者很懂。

六条底盘

1. 工程师视角先于情绪视角:先讲问题、系统、工具、路径,再讲感受和态度。
2. 作者必须真的在场:文章里能看到真实工作流痕迹——为什么碰到、怎么观察、用了什么工具/trace/命令/代码路径、哪步最易误判、自己怎么下判断。
3. 结构感强,标题自己会说话:读者扫标题就应该知道全文骨架。
4. 判断明确,但必须交代依据和边界:给出判断后必须跟依据、条件、适用范围。
5. 技术表达敢写实:工具名、模块名、类名、轨道名、参数、版本、路径、命令都敢写具体。
6. 结尾克制,不做空洞升华:技术文章收束即可,不要硬拔高度。

信息密度

目标不是"每句都很满",而是"每句都推进理解"。

• 一段只做一件事:下定义、解释机制、展示证据、下判断,不要乱炖。
• 高密度解释段中间要插入短结论句/列表/图表/代码观察点,给读者换气。
• 不要连续塞 4 个以上新概念,必要时拆段。
• 核心观点全文只出现 2 次:定义 + 总结。中间段落直接使用,不再反复解释。
• 删掉后不影响理解的段,就是"正确的废话",删。

呼吸感

呼吸感不是抒情,是认知负担控制:

• 长解释段后面跟一句短判断。
• 复杂机制前先给全景图。
• 长代码块前先说"你只需要看哪几行"。
• 关键节点加读者引导,例如:先记住一个结论:... / 到这里,你应该已经能区分 A 和 B。

可读性优先于表面完整

展开顺序:问题是什么 → 为什么值得看 → 先建立整体图 → 再下钻细节 → 最后给判断和边界。不是所有东西都要一次讲完,按读者的理解顺序讲。

---

二、文章结构

常见 5 类长文

1. 技术深度/系列解析:讲清机制、观测方法、分析路径。结构:问题定义 → 背景概念 → 系统流程 → trace/代码/图示 → 实战建议。
2. 工具实战/架构复盘:说明为什么这样设计、怎么落地、踩过什么坑。结构:起因 → 关键判断 → 方案拆解 → 取舍 → 边界。
3. FAQ/Q&A:把读者最关心的问题逐个说透。结构:问题列表 → 逐题结论 → 证据/误区/边界。
4. 方法论/行业观察/判断型:把分散经验提炼成判断框架。结构:现实问题 → 作者判断 → 拆维度 → 反例/代价/边界。
5. 工具体验/读书/社群/人物:有个人色彩但仍然交付实用价值。结构:缘起 → 内容/工具/观点 → 作者补充理解 → 推荐/总结。

默认骨架

【开头】直接交代问题、场景、文章任务
  ↓
【背景】为什么值得聊,读者能带走什么,需要哪些前置知识
  ↓
【主体】按 3 到 8 个板块展开,每块只解决一个问题
  ↓
【判断】把局部观察提炼成更高一层的理解
  ↓
【结尾】压缩结论、补边界、给后续阅读或行动建议

开头

三句内必须完成三件事:这篇在讲什么、为什么值得看、读者看完能带走什么。

四种常用开头:

• 系列定位型:本文是 XXX 系列的第 N 篇,主要讲 YYY。
• 近期事件/读者反馈型:上一篇发出去之后,大家最常问的是...
• 认知修正型:先说原先怎么想,再说真正用过后发现什么。
• 先给判断型:开头先给判断,再展开理由和边界。

开头禁区:

• 不要从"在这个时代""随着技术发展"开讲。
• 不要先讲大背景,再慢慢靠近主题。
• 不要先端一个正确废话当帽子。
• 不要把目录感写成汇报感。

主体

• 一段一义:每段只承担一个任务,不要在一个段里同时做 3 件事。
• 先给全景图,再下钻:整体图景 → 关键模块 → trace/代码/数据 → 结论。
• 关键节点做读者引导:先建立整体图景。 / 到这里先记住一个区别。 / 下面再看这个结论是怎么来的。
• 顺序设计:先放基线,再放进阶例子,最后放最能改写理解的例子。
• 概要和详述分工:如果有"概要"和"展开"两个章节,概要只点结论(2-4 行),展开负责细节。同一内容不在两处各写一遍。
• 系列文章不重述:前文已定义的概念,后文引用即可,不重新展开。
• 模仿别人时模仿结构不模仿句式:借鉴的是判断组织方式、证据编排顺序,不是表面句式和历史排版噪音。

句式与节奏

1. 先直说,再展开:第一两句就把中心说出来,不要兜圈。
2. 长句装信息,短句落锤:长句交代背景/边界/对象,短句下判断。
3. 不用第一人称:不写"我认为"/"我建议"/"我通常会"。直接给结论或步骤。
4. 真实细节可借,表演感不可借:犹豫、取舍、踩过的坑可以出现;强情绪喷发、网络口癖、戏剧化段子感不可以。

结尾

优先四种收法:

1. 一句判断收尾。
2. 正文后给 references/延伸阅读。
3. 给读者下一步动作。
4. 回扣开头问题一次,不做文学化回环。

结尾禁区:

• 不要突然上价值。
• 不要把结论写成口号。
• 不要假装开放式结尾其实什么也没说。
• 不要把全文又空泛复述一遍。

---

三、禁用词与句式

判断标准贯穿全节:删掉这个词/句之后,技术信息量有没有变化?没变化 = 填充,必须删。

3.1 词库

见到即判不合格。同一个词可能在多类都出现——词库按被误用的语境分类,方便查。

大厂黑话/抽象职场词 赋能、闭环、底座、抓手、下钻、落地、对齐、沉淀、打通、串联、链路、心智、颗粒度、组合拳、护城河、矩阵、生态位、赛道、痛点、蓝海、红海、方法论输出、形成共识、统一认知、价值闭环、全链路、全局最优、打法。

汇报腔 先说判断、综上所述、一言以蔽之、直奔主题、值得重点关注、不难看出、显然、众所周知、总而言之、需要注意的是、可以看到、某种程度上、从某种意义上说、核心在于、归根结底、简而言之、总的来说。

网络梗与夸张情绪词 YYDS、绝绝子、破防、拿捏、上分、炸裂、封神、降维打击、赢麻了、核弹级提升、雪崩式炸裂、魔法般生效、一招封神、彻底颠覆一切。

AI 套话(清嗓/强调/填充/模糊四类合并,AI 最容易自动补出这类词)

• 清嗓:说实话、老实说、坦白说、不得不承认、事实上、实际上、关键是、重要的是、有趣的是、值得注意的是、问题是、真正的问题是、这让我想到、这启发了我、不得不说、需要指出的是、不得不提的是。
• 强调:这一点很重要、这很关键、这至关重要、毋庸置疑、毫无疑问、显而易见、不言而喻、由此可见、这就意味着、值得深思、发人深省。
• 填充:在当今社会、在现在这个时代、在当前环境下、在当今、随着技术的不断发展、随着 AI 的快速发展、从根本上说、总而言之、综上所述、总的来说、简而言之、归根结底。
• 模糊:具有深远意义、影响巨大、意义重大、至关重要、不可或缺、举足轻重、意味着什么、这意味着、本质上、换句话说、不可否认。

AI 元叙述词(正文里讲自己的写作过程) 接下来我将、下面我们来看、让我们来探讨、我想说的是、我要强调的是、让我们来看看、接下来让我们、首先、其次、最后。

3.2 限制句式

"不是 X 而是 Y" 这一族整篇文章最多 2 次,超过即 AI 味:

• 不是 X,而是 Y
• 不只是 X,还 Y
• 并非 X,而是 Y
• 不仅仅是 X,更是 Y
• 与其说是 X,不如说是 Y

3.3 禁止模式

下面这些模式不是"谁都能判"的词,要带判断去改。示例格式:给错误写法,给修正写法。

底层解释:AI 味在根子上是翻译腔。AI 生成中文时像是先在英文句法里想清楚意思,再一个字一个字换成中文——每个字都是中文,语法也合规,但句子的骨架、主谓搭配、动词选择、段落节奏,全是英文的。下面很多模式都是翻译腔留下的具体痕迹,认出骨架来源比靠"语感"更稳——句子读起来别扭但挑不出单词毛病时,多半是骨架问题。

3.3.1 否定-纠正结构

模式:不是 A,而是 B 问题:先否定一个读者可能没想过的错误理解,再给正确描述。直接说 B 就够了。

3.3.2 假想读者错误

模式:误以为 / 很多人会以为 / 读者可能 问题:预设读者有错误认知再纠正。读者可能根本没这么想,反而被带偏。

3.3.3 口水过渡词

模式:其实 / 更准确地说 / 更贴近现代 X 的理解是 问题:暗示前文不够准确。技术文章一次说对就行;觉得前文不准确就改前文,不要追加修正。

3.3.4 比喻降格

模式:你可以把 X 理解成 Y / 你可以把 X 先记成一句话 问题:把精确的技术描述包装成口语化比喻,降低信息精度。允许比喻做脚手架,不允许代替技术解释。

3.3.5 虚假引导语

模式:先别急着 / 先记住一点 / 这里有一个关键点要讲清楚 问题:给读者设置心理缓冲,暗示"内容很难"。

3.3.6 冗余确认副词(重点,高发)

模式:真正的 X / 真正 / 真的 / 确实 / 实际上(作为修饰语) 问题:这类词最容易逃过禁用词检查——单独看每处都"说得通",累加到全文就是典型 AI 味。

判断:删掉这个词,技术信息量有没有变化?

保留(有两个对照对象):

• CPU 提交返回不等于任务完成,GPU 真正写完 buffer 后 fence 才 signal(对照:API 提交 vs GPU 实际完成)

删掉(没有对照对象,只是强调):

• 真正的 Producer 是 Camera HAL → Producer 是 Camera HAL
• 真正决定最终成本的,是 HWC 决策 → 决定最终成本的,是 HWC 决策

section 标题里的"真正"全部按填充处理——标题最精练,对比关系放进句式,修饰词删掉。

全文高频自检:单一词命中 >= 5 次视为 AI 味,要压到 2-3 次——即使每处单独看都算功能性。靠改句式把强调藏进结构里,不要反复依赖同一个词。

3.3.7 物理动作动词(翻译腔套路一)

模式:把思考过程、判断关系、状态描述成物理动作。 问题:英文里 catch a point / sharp argument / blow up / hold harder / break 都自然,因为英文背后有棒球、刀刃、物理崩塌这些生活经验。中文没有这套生活,直接翻过来的动词就"悬空"。

高危词库:接住、击穿、拆解、收口、承担、撑不住、不崩、不爆、打穿、打透、收紧、推开、扛住、立住、站稳、锋利、硬(作判断的"硬"度)。

规则:技术文章用中性动词——建立、呈现、展开、确认、得出、收到、记下、站不住、压不住。力量感是副作用,不是目标;靠准确说清事实。

3.3.8 结构性元叙述

问题:比词库里的"AI 元叙述词"更隐蔽——看起来在为读者指路,实际是 AI 在背诵结构模板。

• "本节只讲 A,B 放到下一节"
• "这一节先把三条核心结论摆出来,下一节再展开细节"
• "下面先讲 A,再讲 B,最后讲 C"

规则:章节标题和段落顺序本身就是结构表达,不要再用正文元声明一遍。

3.3.9 形容词 + 冒号起手式(翻译腔套路二)

模式:X 很 Y:[内容] / 更 Y 的 X:[内容] / 很 Y 的是:[内容] 问题:抢走读者自己评估的机会;形容词几乎总是多余;英文原型 Quite simply, ... 在英文里早被诟病为公文腔。

规则:直接把形容词那一节删掉,只留后半句事实。

3.3.10 抽象名词做主语 + 形容词做结论(翻译腔套路三)

模式:X 的 Y 比 Z 更 W / X 的 Y 是 W 的 问题:英文 The reality is uglier than... 的直译。

规则:让人、动作、或者具体对象做主语,让事实自己说话。

3.4 格式规范

• 中英文空格:英文单词/代码标识符两侧加半角空格。
• 硬换行:markdown 段落里不要在半句话中间硬换行。
• 列表/代码块中允许换行,正文段落中不允许断在名词或短语中间。

---

四、展示规范

代码

1. 代码块前必须有"用途句":交代这段要证明什么、读者重点看哪里、看完要得到什么结论。
2. 代码块内要可读:用标准 Markdown 代码块并标注语言,命名/缩进/换行遵循语言 style guide。
3. 可以省略但要明确:用该语言的注释标明,别用含糊的 ...。例如 // Several unrelated lines are omitted.
4. 代码后必须有"解释句":解释为什么这里关键、如何和上文结论对应、读者实战里怎么观察。
5. 大段代码的处理:正文只保留骨架和关键路径,过长代码放仓库/Gist/附录。
6. 代码质量:能运行的给可运行版本;不能运行的明确说明是"示意/伪代码/节选";不准编造不存在的 API/类名/方法名。

数据

1. 先决定表达形式:一句话能说清用文字,少量对比用列表,多指标对比用表格,趋势/波动用图表,时序关系用流程图。
2. 数据必须有参照物:任何数字都要补单位、测试条件、对比基线、是否稳定复现、样本范围。
3. 表格不是堆料区:只放读者需要横向比较的字段。
4. 图表不是装饰:要回答一个明确问题。
5. 结论必须回连数据:图表/表格后面必须补一句解释这组数据支持/不支持什么。

列表

**核心原则:列表不能是目录,必须是内容。**每个列表项必须自带信息增量,读者读完该项就知道"这是什么/为什么/怎么用"。

判断标准:删掉列表项后面的描述只留名词,读者会不会少知道什么?如果不会,说明描述不够。

图表

图表类型	工具	代码围栏	适用场景
流程图/时序图/状态机	mermaid	```mermaid	管线流程、时序、状态流转
分层架构图	architecture	```architecture	系统架构、模块分层
数据图表(柱/折/散点/热力图)	vega	```vega-lite	性能曲线、对比、趋势
复杂依赖/调用图	graphviz	```dot	类继承、调用链、模块依赖树
信息卡片/时间线/对比	infographic	```infographic	效果对比、工具评分、方法论总览
思维导图/知识图谱	canvas	```canvas	知识体系结构、概念关系

选择原则:能用 mermaid 的不用 graphviz;数据对比优先 vega;架构分层优先 architecture;公众号文章优先 mermaid 和 infographic(渲染兼容性好)。

术语

• 有稳定中文译法的英文词必须换成中文。AI 生成的中文里常留原样英文——context、state、cache、claim 之类,读者每次要在脑子里切换。
  • 已有稳定译法的一律翻译:上下文(不是 context)、状态(不是 state)、缓存(不是 cache)、断言(不是 claim)、运行时、协议层、契约层。
  • 仍在抢的术语保留英文:prompt、embedding、tokenizer、harness、agent 等——这些在中文技术圈还没收敛到通用译法。
  • 判断标准:中文圈里讨论这个概念有没有统一术语?有就换中文;没统一就保留英文。
• 一类例外:已经成为专有名词/标识符的英文保留——Android、Perfetto、Kubernetes、Docker、Workflow、Agent 等。
• 第一次出现的新概念,先给一句人话解释,再展开。
• 不要为了"通俗"牺牲精确性——不要把术语解释成另一个更空的术语。

---

五、AI 协作规范

AI 擅长做的

• 整理资料、提纲、目录
• 把已有观点扩成更完整的结构
• 给出多个解释版本帮选更易懂的
• 补全可读性检查项,找黑话/重复句/AI 味句式
• 协助整理表格/清单/对比矩阵
• 按既定角度扩写已有段落

AI 不能替你做的

• 决定文章的核心角度
• 编造第一手经验/实验/trace 观察/性能数据
• 替你承担技术正确性
• 替你做最终取舍和判断
• 假装它真的跑过你的工程环境

协作流程

人:给出主题、读者对象、自己的判断、真实经历、关键证据
  ↓
AI:整理结构、补参考资料、提出可读性优化方案
  ↓
人:补一手细节、删错的、改判断、压风格
  ↓
AI:按四层质检做检查,指出具体问题
  ↓
人:终审,确认准确性、边界、可发布性

硬规则

• 不能把 AI 生成的"像真的"当成"真的"——必须核实。
• 不能让 AI 自动补齐不存在的实验结论。
• 不能把 AI 的平滑表述原样端上去——必须二次改写。
• 不能一轮生成直接发布。
• 不能抄别人的框架/观点不标来源。
• 发布稿只面向读者,不留编辑痕迹:正文中不出现"这一版"/"上一稿"/"按你说的"等写作过程记录。

---

六、质检体系

写完后执行四层质检,任何一层不通过都需要修复后再检查。

L1 硬性规则(零容忍)

命中即不合格:

• 禁用词:第三节词库(3.1)零命中。
• 事实正确:版本、路径、工具名、类名、参数值不能乱。
• 代码规范:代码块标语言;省略代码有明确注释;不贴代码截图。
• 数据规范:数据有单位、条件、基线或解释。
• 格式:按 3.4 检查中英文空格、硬换行、Markdown 层级。
• 比喻:没有夸张比喻、没有多层套比喻。
• 高频词自检:对 真正|实际上|其实|根本|彻底|确实 做全文计数,单一词命中 >= 5 次视为不合格(按 3.3.6 判断标准压到 2-3 次以内)。
• 结构性元叙述:3.3.8 列出的那几类元声明零命中。

L2 可读性

• 开头:三句内进入主题并交代读者收益。
• 节奏:长短句交替;高密度部分有呼吸点;连续四句以上句式长度相近 = 节奏呆板。
• 结构:段落之间有自然过渡;每个板块有一个明确核心观点;整体有清晰的推进线。
• 读者视角:读完每段能回答"这一段在说什么";没有需要回头重读才能理解的逻辑跳跃;专业术语有足够上下文。

通过标准:开头必须通过;4 项中至少 3 项通过。

L3 内容深度

• 论据支撑:每个核心判断至少有经验/数据/代码/图/引用之一支撑。
• 知识输出质量:技术解释从"为什么存在"开始再到"怎么工作";不是聊天式顺带出来,也不是教科书式硬塞。
• 独创性:有"换了别人写不出这个角度"的内容;不是通篇"正确但无信息增量"的常识。
• 对立面与客观性:涉及判断时考虑了反方观点;没有"只说好处不说代价"的片面性。
• 可执行性(仅限教程/方法论类):每个建议落到"今天就能做"的具体动作;坦诚说明学习成本和常见失败点。

通过标准:论据支撑和知识输出质量必须通过;其余 3 项至少 2 项通过(不适用跳过)。

L4 活人感终审

核心问题:读完这篇,是一个有经验的人在认真分享,还是 AI 在批量输出?

• 温度感:情绪表达是体感的("我当时觉得不对劲")还是知识性的("我感到非常困惑")?
• 独特性:有作者个人视角的痕迹(个人经历/独特判断/特有表达习惯)还是去掉署名后完全猜不出是谁写的?
• 姿态:语气是"同行在分享经验"还是"导师在教学生"?有没有滑入说教/营销/汇报腔?
• 心流:从头到尾读,有没有注意力断掉需要回头理逻辑的地方?
• 骨架感:随机抽 3-5 段,试着把每句话"无损"翻回英文。如果大量句子顺顺当当就能翻过去,骨架就是英文的——整体是翻译腔,按 3.3.7-3.3.10 处理。

通过标准:整体感觉"像是真人写的"。任何一项感觉"AI 味太重"就需要返工。

质检报告格式

---
## 四层质检报告

**L1 硬性规则** pass/fail
- 禁用词:X 处命中(列表)
- 事实硬伤:X 处 / 无
- 格式:X 处不一致(含硬换行)
- 高频词:`真正` X 次 / `实际上` X 次 / ...(任一 >= 5 = fail)
- 结构性元叙述:X 处

**L2 可读性** pass/fail
- 开头、节奏、结构、读者视角:逐项 pass/fail

**L3 内容深度** pass/fail
- 论据支撑、知识输出、独创性、对立面、可执行性:逐项 pass/fail/不适用

**L4 活人感** pass/fail
- 温度感、独特性、姿态、心流:逐项 pass/fail

**总评**:4 层全部通过 / L1/L2 需修复后重检 / 建议人工复审
**最需修复**:[1-3 个具体问题]

约束:

• 质检只输出报告,不自动修改内容。
• 问题必须具体到段落/位置,禁止空泛评价。
• L4 通过不了时,给出"哪个段落 AI 味重"的具体指引。
• 质检报告不计入正文落盘。

---

七、精修 mode

用户让你"精修一篇已写好的文章"(不是重写,不是评审)时用这套工作流。

精修 vs 重写的边界

动作	精修
删冗余词/AI 填充词	可以
改一句话内的否定-纠正结构	可以
修格式问题(硬换行、中英文空格)	可以
改单句表达(让它更直接)	可以
删一个明显冗余的段落	谨慎
改段落顺序	不可以,属于重写
改章节结构	不可以,属于重写
改作者的技术判断	不可以,属于重写
补充新论点/新证据	不可以,属于重写

原则:精修只动词句,不动结构;只删冗余,不改事实;保留作者原有判断和表达习惯。

审查工作流

第一步:填充词 grep 初筛

真正|本质上|恰恰|其实|显然|众所周知|不言而喻
说实话|事实上|实际上|关键是|重要的是
值得注意|不得不说|需要指出

第二步:逐处按"功能性 vs 填充性"判断(标准见 3.3.6)——有对照对象、删掉会丢信息就保留;无对照对象只是强调就删。

第三步:翻译腔动词 grep(套路一,见 3.3.7)

接住|击穿|拆解|收口|不崩|不爆|打穿|打透|收紧|推开|扛住|立住|站稳|锋利|硬得|claim|catch

命中即判断"中文日常里会不会这样用",不会就换中性动词。

第四步:翻译腔句式扫描

• X 很 Y:[内容] 的起手式(套路二,3.3.9)——冒号前是形容词评价就删
• X 的 Y 比 Z 更 W 骨架(套路三,3.3.10)——重写成具体主语 + 动作谓语
• context|state|cache|claim|runtime 等原样英文(套路四)——换成上下文/状态/缓存/断言/运行时

第五步:格式扫描——硬换行断名词、section 标题里的填充词、中英文空格不规范。

第六步:逐一判断否定-纠正结构(3.3.1)——读者没预设那个错误认知就删否定直接陈述 B。

第七步:虚假引导语(3.3.5)和结构性元叙述(3.3.8)扫描——找 先记住 / 先别急着 / 这里要 / 本节只讲 / 放到下一节,逐个判断。

改动优先级

同样的 AI 味在不同位置严重性不同:

1. 最优先:section 标题里的填充词(最刺眼,标题该最精练)。
2. 次优先:每节开头第一句、结尾结论句(读者最容易盯到)。
3. 再次:列表项开头(短句里填充词比例高)。
4. 中等:段落首句(给段定调的位置)。
5. 最低:长段落中间(填充词混在长句里不明显,硬改有时反而破坏节奏)。

时间有限时先扫 1-3 档,4-5 档列在备注里交回用户。

改动克制

• 改动数量和 AI 味浓度挂钩——原稿越干净改动越少。经过前序审查的稿子控制在 5-10 处以内。
• 不"为改而改":原句读起来自然、信息准确就别动。
• 不统一口吻:作者的表达习惯(偏口语/偏书面、短句/长句比例)是"活人感"的来源。
• 改完自己回读一遍,确认没因为删填充词而让句子反而不通。

翻译腔的根治方法(归化重写)

遇到一段 AI 生成的中文读着别扭但不好改单词的——圈不出具体病句,但通读起来就是不对——这是骨架问题,不是词句问题。单词级别的精修修不掉,必须重写。

方法:

1. 读完原段,确认意思(事实、判断、边界);
2. 把原段盖上(物理遮住或关掉,不看着原文);
3. 用中文里本来会怎么说这件事,重新说一遍;
4. 再对一遍,确保没漏事实。

什么时候一定要走这一步:一段话圈不出具体病句但读两行就能认出是 AI——句句都能顺翻回英文——这是骨架翻译腔,只有重写能治。

什么时候不该走:原稿作者本来就是用中文骨架写的,只是偶尔有几个 AI 填充词——这种按正常精修走,别重写。重写风险是会丢掉作者的原意和原语气。