体验日志与发布说明二者之间的区别到底是什么
阅读约 1 分钟 更新于
体验日志是一份持续累积、记录所有变化的记录，写给那些正在查找某个具体信息的人看。发布说明则是关于某一个版本、经过挑选的一条消息，写给那些还在决定这次更新是否与自己有关的人看。二者的区别在于目标读者，而不是格式，大多数团队其实两者都需要：一份作为参考资料，一份作为公告，都源自同一批条目。
大多数团队最终会因为一种偶然拥有其中之一，再因为一次请求拥有另一个。你一开始建立体验日志，是因为某个开发者想要一份已发布内容的记录。几个月后，支持团队的某个人会问，为什么客户不知道那个自四月起就已经上线的功能，于是你就需要发布说明了。
体验日志与发布说明的并排对比
| 体验日志 | 发布说明 | |
|---|---|---|
| 读者 | 正在查找某个信息的人 | 正在决定是否关心的人 |
| 范围 | 所有发生的变化 | 关于这次发布值得说的内容 |
| 频率 | 持续更新，每次合并或每次发布 | 每次发布一次，只发布值得公告的版本 |
| 语气 | 简洁、客观，常用祈使句 | 解释性的，有时带说服意味 |
| 生命周期 | 永久保留，多年后仍会被查阅 | 第一周被阅读，之后归档 |
| 存放位置 | 代码仓库、文档站点、/changelog 页面 | 邮件、应用内、博客文章、发布页面 |
| 失败方式 | 因为不完整而失败 | 因为无趣，或来得太迟而失败 |
什么是体验日志
体验日志是按时间顺序、几乎完整地记录变化的清单，最新的排在最前，每条都标注类型（新增、变更、废弃、移除、修复、安全）和日期。它的读者已经决定要关心了，他们正在查找某个信息：某个行为是什么时候变的，某个 bug 有没有修复，哪个版本引入了某个开关。完整性就是它的全部价值，这也是为什么 Keep a Changelog 这个惯例，在短短一页里几乎把全部篇幅都用在了结构上，几乎没有花在措辞上。
什么是发布说明
发布说明是关于某一个版本、经过挑选、用散文写成的一条消息。它的读者还什么都没决定，他们正在判断这次发布是否与自己有关，以及自己是否需要为此做点什么。挑选就是它的全部价值：一份把所有东西都列出来的发布说明，不过是加了几段话的体验日志，它辜负读者的方式，和一份漏掉重要内容的体验日志辜负读者的方式是一样的。如何写发布说明一文谈的就是这种挑选和措辞。
体验日志和发布说明是不是都需要
一旦两个读者群体想要的东西开始不同，你就两者都需要；在那之前，用一份成果物同时承担两个职责是对的。小团队会发布一个单一的 /changelog 页面，在每条条目的开头加一小段说明，在一段时间里，这样既能服务查找修复信息的开发者，也能服务浏览新闻的客户。拆分得太早，只会让你多出两样东西要维护，其中一样注定会腐坏。
出现以下情况时，拆分就值得了：
- 你的体验日志条目开始长出开发者会直接跳过的解释性段落。
- 或者反过来：你的发布公告里开始列出依赖升级信息。
- 支持团队正在把条目复制进邮件，并在途中重写它们。
- 有人要求”只看破坏性变更”，而你无法为他们筛选出来。
最后一条才是真正的信号。如果不读完全部内容，就没人能回答”哪些变化影响到了我”，那说明一个成果物正在勉强承担两个职责，而且都做得不好。
一个来源，两种视图
常见的错误是把它们当成两份文档来对待。它们其实是同一批变化的两种视图。
在开发过程中就写体验日志，每个有意义的变化一条，各自标注它是什么：修复、新增、变更、移除、废弃、安全。让条目保持足够简短，写一条不需要费心决策。然后，在发布时，发布说明就是一次挑选和重写：挑出对人有意义的条目，按照它们能让人做成什么事来分组，把原因放在最前面。
这带来一个实际的结果。如果体验日志是数据来源，它就需要是结构化的数据，而不是手工维护的页面。一条条目需要有类型、日期、版本，以及说明它是给谁看的方式。一旦具备了这些，公开页面、应用内小组件和 RSS 或 JSON 信息流就都是同一份东西的三种渲染结果，途中没有人需要重写任何内容。发布说明邮件也可以引用同一条条目，无论你用什么工具发送邮件。体验日志自动化谈的就是这几个步骤中，哪些应该交给机器负责。这就是把体验日志当作一个信息流而不是一个页面来处理的全部理由。而且坦白说，这正是我们在做的产品，所以请把这段话当作利益相关的立场，而不是中立的调研结论来看。
如果你只有时间做一件事
写体验日志。它每条的成本更低，写下的当天就有用，而发布说明之后可以从它推导出来。反过来则不成立：你没办法从十二封公告邮件里，重新拼出一整年的变化记录，而人们总会向你要这份记录。
把它维护成固定的格式，这样推导才始终可行。我们的体验日志范例页面收集了那些把体验日志做得很好的团队的条目，发布说明模板则是我们在把一批条目变成值得发送的内容时所用的格式。
关于命名的一点说明
这方面并没有统一的标准，你会看到有人把”release notes”用来指持续更新的列表，也有人把”changelog”用来指季度公告。为这些词争论并不值得。决定你的每个成果物到底承担哪一种职责，用团队已经在用的名字去称呼它，并确保任何一个都没有在悄悄地同时承担两种职责。
结果最终落在哪个表现形式上，是一个独立的决定，如何搭建体验日志页面一文有详细说明。
FAQ
体验日志和发布说明是同一回事吗? 不是。体验日志是完整的记录，供正在查找信息的人阅读；发布说明是经过挑选的公告，供正在决定是否关心的人阅读。同一个变化会出现在两者中，但针对不同的读者会用不同的措辞。
发布说明可以从体验日志生成吗? 可以，而且这才是正确的方向。挑出人们会关心的条目，按结果分组，重写标题。反过来，从公告去重构体验日志，会丢失公告里省略掉的一切内容。
体验日志应该放在哪里?
放在一个永久、可链接、读者无需仓库权限就能访问到的地方：一个 /changelog 页面、一个文档站点，或者一个可以渲染到多处的信息流。单独一份 CHANGELOG.md 只能触达贡献者，触达不了客户。
体验日志应该包含内部变更吗? 应该，放在最后，每项一行。体验日志是完整的记录。发布说明也可以保留它们，放在末尾一个简短的小节里，只要读者会注意到的那些变更排在前面就行。
本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。