7 交流！ — remuse

按受众、目的、时机和媒介设计沟通，并把文档、代码和决策记录放进同一条可更新链路。

学习目标

能把“7 交流！”拆成受众、意图、结构、媒介和反馈，并用理解证据验证沟通是否完成
能用“提示11：英语就是另一门编程语言”和“提示12：说什么和怎么说同样重要”调整术语、信息层级、时机和媒介
能按“提示13：把文档嵌进去，而不要栓在表面”把文档源头接入代码、测试和决策更新，并记录误解、首差与回退

为什么 7 交流！不是软技能附录

本页依据 David Thomas、Andrew Hunt《程序员修炼之道：通向务实的最高境界（第2版）》，云风译，电子工业出版社，2020年4月，ISBN 9787121384356 的公开完整中文目录，独立重构 7 交流！。本页不复制原书正文、插图、练习答案或代码，而把目录命题转写成沟通契约、文档回路、反例和复核证据。

交流的产物不是“说过了”，而是对方能在约定边界内做出正确下一步。一次技术决定可能同时面对用户、开发者、运维和决策者；他们的词汇、风险、时间和行动都不同。若只发出同一段信息，发送者可能完成了表达，接收者却没有形成可验证的理解。

本单元把沟通建模为 受众 → 意图 → 信息形状 → 媒介与时机 → 理解检查。每一步都写清负责人、输入、可见产物和拒绝条件；沟通失败时回到最早出现误解的步骤，而不是把失败归因于“对方没认真看”。

四个目录命题的验收合同

目录命题	操作对象	可观察产物	失败时的动作
7 交流！	受众模型与沟通目的	沟通契约、决策或下一步	重新确认对象和行动，不重复发送原文
提示11：英语就是另一门编程语言	术语、例子和句子结构	领域词汇表、示例和反例	标出未定义词，改写后让目标受众复述
提示12：说什么和怎么说同样重要	内容、层级、时机和媒介	分层消息、渠道选择和理解检查	保留命题，重排表达方式并比较误解
提示13：把文档嵌进去，而不要栓在表面	文档源头和更新触发器	与代码、测试或决策绑定的文档	找出第二个真相来源，合并并加更新检查

Audience Model 不是一句“面向所有人”，而是写出角色、已有上下文、要完成的行动、不能接受的风险和验证理解的方式。

Communication Intent 把“通知一下”改成可检查的结果，例如让值班工程师在五分钟内决定是否回滚。

Information Shape 决定先给结论、风险还是操作步骤；它不是给同一份内容换一个漂亮标题。

Understanding Check 要观察受众实际做了什么，而不是只记录“已读”或会议里点头。

Embedded Documentation 让说明成为交付链的一部分，源头变化时有检查、责任人和失败提示。

7 交流！：先建立沟通契约

先写 Audience Model 和 Communication Intent：谁要在什么场景下做什么决定，错误理解会造成什么代价。再选择 Information Shape、媒介和时机，最后安排 Understanding Check。这样做不是增加表格，而是让发送者和接收者共享一个可复核的行动边界。

例如发布一个兼容性变更时，用户需要看到影响和迁移步骤，开发者需要看到接口差异和测试，决策者需要看到风险、成本和回滚窗口。三份表达可以来自同一份决策源，但不能假定三类受众共享同一套词汇和优先级。

沟通契约把“说过了”推进到受众完成正确行动。

提示11：英语就是另一门编程语言

把语言当作编程接口来设计：名词要稳定，动词要指向行动，示例要覆盖正常和拒绝路径，缩写要有边界。团队先建立面向当前领域的词汇表，再检查同一个词是否在产品、代码、支持和运营语境中被赋予不同含义。

这并不要求所有人使用英语，也不意味着自然语言能够像编译器一样消除歧义。它要求我们像设计 API 一样对待表达：声明前提，减少隐含状态，给出输入与输出，并用一个真实任务验证对方能否执行。术语表本身也要记录 owner、版本和废弃词，避免把旧称呼留在搜索结果和模板里。

提示12：说什么和怎么说同样重要

“说什么”是命题、证据、约束和请求；“怎么说”包括顺序、粒度、格式、媒介、时机、语气和反馈入口。相同的事实，在事故进行中应该先说影响、责任人和安全动作；在复盘中则需要时间线、证据、替代方案和系统性改进。把二者混为一谈，会让正确内容在错误时机失效。

先保存不可变的核心命题，再为不同受众生成 Information Shape。页面可以先给结论和影响，代码注释可以贴近约束，会议可以用决策问题组织讨论，异步记录则要让缺席者重建背景。每一种媒介都要有 Understanding Check，例如复述、演练、选择题、测试结果或用户完成任务的记录。

提示13：把文档嵌进去，而不要栓在表面

文档应靠近它解释的事实源：接口契约与类型或测试绑定，运行手册与监控和发布步骤绑定，决策记录与变更请求绑定。将内容复制到 wiki、聊天和幻灯片后再靠人工提醒同步，会产生多个看似正确的真相来源。

Embedded Documentation 的最小合同包括源头、责任人、触发器、更新检查和失效提示。源头变化时，测试、构建检查或评审清单应能指出需要更新的文档；如果文档暂时不能自动检查，也要把人工检查写成发布前的明确动作，并保留最近一次验证时间。

把文档嵌入交付链，才能让事实变化带着说明一起前进。

两张图，三步走完一次沟通

分步1 / 3

先描述受众与意图

填写 Audience Model 和 Communication Intent，写出受众已有知识、要完成的行动、拒绝条件和验证方式。不要从“我要介绍这个技术”开始，要从“对方要据此做哪一个决定”开始。

沟通契约把“说过了”推进到受众完成正确行动。

可执行的沟通记录

communication_record:
  unit: tpp20-topic-07-communicate
  audience_model: 值班工程师、受影响用户、发布负责人
  communication_intent: 判断是否暂停发布并选择回滚或迁移
  information_shape: 结论与影响 -> 证据 -> 操作步骤 -> 边界
  medium_and_timing: 告警页面即时通知，决策记录异步补全
  understanding_check: 值班工程师演练回滚，用户完成迁移步骤
  embedded_documentation: 接口测试、发布清单、决策记录
  update_trigger: 契约、测试或回滚步骤变化时阻止过期文档发布
  first_mismatch: 受众把兼容性警告理解成无需行动
  recovery: 改写术语和首屏层级，重新演练并记录结果

这个记录把“交流成功”拆成可重建的证据。它不追求一个总分：若受众能够复述命题却没有完成行动，Understanding Check 仍然失败；若文档内容正确但源头变化后无人收到提醒，Embedded Documentation 也仍然失败。

反例与边界

场景	看似合理的做法	实际缺口	应保存的证据
产品发布	给所有人发同一篇长公告	受众无法找到与自己行动有关的段落	各角色的行动入口和复述结果
事故处理中	先写完整背景再给安全动作	时机错误，值班人员错过回滚窗口	告警时间、首个动作和恢复结果
接口变更	在 wiki 复制一份新说明	代码和文档形成两个源头	契约测试、源头链接和更新失败记录
术语迁移	直接批量替换旧词	领域含义和用户习惯可能不一致	词汇表、反例、搜索范围和用户反馈

反例不是“有人不喜欢这种写法”，而是同一个 Communication Intent 在特定受众、时机或媒介下没有产生预期行动。先指出边界，再决定是换 Information Shape、换渠道、补理解检查，还是改变原本的命题。

常见误区

本章回顾

掌握 7 交流！，不是让每个人写出同样的文章，而是能从 Audience Model 和 Communication Intent 出发，按提示11把术语当作接口设计，按提示12同时校验命题与表达方式，再按提示13把文档嵌入代码、测试和决策源。最终证据是受众完成了正确行动，文档源头变化时也能触发更新，而不是“我已经说过了”。

可验证练习

练习

本组练习覆盖 7 交流！、提示11：英语就是另一门编程语言、提示12：说什么和怎么说同样重要、提示13：把文档嵌进去，而不要栓在表面。每题提交 Audience Model、Communication Intent、Information Shape、Understanding Check 和 Embedded Documentation 的证据。

问题 1： 同一项兼容性变更要同时通知用户、开发者和发布负责人。如何设计沟通契约，并证明三类受众理解了各自的下一步？

问题 2： 如何把“提示11：英语就是另一门编程语言”和“提示12：说什么和怎么说同样重要”用于一次事故通报？

问题 3： 一个接口已经更新，但 wiki、代码注释和发布清单彼此不一致。如何实践“提示13：把文档嵌进去，而不要栓在表面”？

名词解释

本章出现的专业名词，用大白话再讲一遍。

Audience Model: 记录角色、已有知识、风险、目标行动和理解验证方式的受众描述。
Communication Intent: 沟通要促成的判断、选择或行动，以及不应被误解的边界。
Information Shape: 按受众组织命题、证据、层级、顺序、例子和行动入口的方式。
Understanding Check: 通过复述、演练、测试或实际结果验证受众理解和行动的证据。
Embedded Documentation: 与代码、测试、配置或决策源绑定，并在源变化时触发更新的文档工件。

前后导航

来源与改写范围

Pragmatic Programmer 作者页面：核对 Topic 7、提示11、提示12和提示13的版本位置与主题范围。
中文目录页面：核对 7 交流！、提示11：英语就是另一门编程语言、提示12：说什么和怎么说同样重要、提示13：把文档嵌进去，而不要栓在表面的公开目录范围。
出版社书目信息：交叉核对中文译本的出版信息与版次边界。