体验日志到底是谁在写，又应该是谁来写才对

问一个团队是谁写体验日志，诚实的答案往往是”谁记得就谁写”，这和在 CI 里强制要求体验日志 条目想在机械层面修复的，是同一种失败模式。但强制要求 条目存在，并不能决定谁有资格写出一条好条目，而跳过这个问题的团队，往往会默认交给最容易被 强制的人，通常是 PR 的作者，却从不核实这个人是不是真的能把它写好。

为什么 PR 的作者不会自动成为最好的体验日志作者

因为她了解实现细节，却不一定了解影响，而这是两种不同类型的知识。Conventional commits 在哪里停下从提交信息这一侧讨论了这个鸿沟： fix(auth): reject expired refresh tokens 是准确的，但对客户来说什么都没说，而写下那个 修复的人，往往恰恰是最不适合翻译它的人，因为她已经用那个 bug 的视角思考了好几个小时， 失去了用户实际经历了什么的那种外部视角。这正是技术写作能够作为一种独立职业存在的原因：把实 现翻译成影响，是一种和造出这个东西本身完全不同的技能，不管一个开发者的代码水平有多好，这项 技能都需要专门练习才能掌握。

这是否意味着产品或支持团队应该代替开发者写每一条条目

不是，因为他们有相反的鸿沟：他们知道什么对用户重要，却不总是知道到底发布了什么，这会产生 读起来顺畅但在范围上时而出错的条目，比如给一个仍然藏在功能开关后面的功能贴上”现在已支持 X” 的说法，或者把只覆盖了三种情况中一种的修复描述成已经完成。开发者写的条目的失败模式是难读 但准确，PM 写的条目的失败模式是好读但未经核实。这两种角色都没有独自拥有一条好条目所需要 的两半。

一个真正起作用的归属模型看起来是什么样的

由离变化最近的人写初稿，由离用户最近的人来审核，并由一个被指定的人对最终措辞负责，而不是 让每个人都以为别人会补上问题。比起写得好，初稿更需要的是存在并且准确；一句由开发者写的、 正确说清楚了变化的粗糙句子，是比打磨过但未经核实的句子更好的起点，因为为了清晰而重写，比 为了准确而重写要容易得多。审核这一步，就是 PM 或支持负责人读完初稿后问出那个唯一能抓住 可读性鸿沟的问题的地方：如果我没看过代码，我能理解这一条吗。

应该始终由同一个人负责，还是应该轮换

有指定的、稳定的人选胜过轮换，至少在最终批准这件事上是这样。轮换制的负责人意味着每一条条 目都由一个从零开始重新推导团队惯例的人来审核，这正是语调会随着条目漂移、读者开始察觉体验 日志是由一个委员会写出来的方式。一个人，或者一个非常小的稳定小组，会随着时间积累判断力： 什么时候该说”已改进”，什么时候该点出具体数字，什么时候一个修复需要单独一条条目，什么时候 该并入一批，而这种判断力比把工作平均分配更有价值。

初稿（开发者，来自 PR）：
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

审核后（体验日志负责人，已对照真实 PR 核实）：
"已修复：按日期排序的导出结果，在超过第一页之后可能
返回顺序错乱的结果。现在所有页面都保持一致了。"

一个小团队需要为一行文字投入这么多流程吗

不是把角色当成不同的人，但那两个步骤即便独自一人也依然重要。一个人的团队既是开发者也是 审核者，而在那种规模下能存活下来的纪律，是把审核当作一个独立的心理步骤来完成，而不是从写 修复直接一口气跳到发布对它的描述。小规模下的陷阱是干脆整个跳过第二遍审核，而不是缺少第二 个人，原因是没有任何外部力量强制要求，而那一遍存在的目的正是要抓住的那个准确性鸿沟， 并不会因为同一个人理论上可以自己察觉自己的盲点就凭空消失。

如果没有人对最终的条目负责，会发生什么

体验日志会不均匀地退化，而不是整体崩溃，这更糟糕，因为在读者指出之前没有人会注意到。有些 条目依然清晰锐利，因为写它们的人在乎；另一些则变得含糊，写成”若干改进和 bug 修复”，因为 写它们的人写得很快，而且没有人在发布前抓住这一点。Keep a Changelog 的格式约束，能抓住结构性的漂移、缺失的日期、错误的分类，但模板里没有任何东西能抓住一条 技术上格式正确、内容却含糊不清的条目。这恰恰是一个被指定的负责人存在要去填补的鸿沟。

FAQ

体验日志负责人应该是工程角色还是产品角色? 只要这个人既有足够的技术能力核实范围，又和实现保持了足够的距离，能够为外部读者写作，两者 都可以胜任；头衔的重要性不如她能否同时做到这两半，或者她是否知道自己做不到的那一半该去问谁。

类似值班轮换的排班方式，是否适合用来管理体验日志的归属? 在工作量上有时可以，如果团队太小、一个人无法审核所有内容的话；但在语调和判断力上不行，因为 这恰恰是轮换会侵蚀的东西。一种在保留一位稳定审核者的同时分担初稿写作负担的轮换方式，可以在 不产生漂移的情况下获得那种好处。

当前归属设置出了问题的最快信号是什么? 条目呈现出准确但难读，或者好读但范围有误的模式，而这个模式跟随的是谁写了它。如果质量和作者 相关，而不是保持一致，那么问题出在归属上，而不是写作能力上。

自动化会降低归属这件事的重要性吗? 它降低的是需要多少写作，而不是需要多少判断。体验日志自动化 讨论了流水线可以安全生成的部分：格式化、发布、跨平台同步；措辞、分组，以及什么才算值得一提， 无论流水线自动化了多少，这些始终是人的决定。

如果 PR 的作者和审核者在措辞上有分歧怎么办? 以审核者的判断为准，因为她要回答的那个问题，一个外部读者能不能理解这一条，正是这个角色存 在的意义所在。这并不代表开发者的判断毫无价值：如果分歧其实是关于准确性而不是措辞本身，审 核者就应该让步，因为范围是否正确是作者那一半该负责的事。把这两种分歧，措辞和准确性，区分 开来，大多数争执就不会演变成僵局。

本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。

changeloop 相关页面： changelog 工具对比, changelog 生成器