如何搭建一个人们真的会持续关注的体验日志页面
阅读约 1 分钟
一个体验日志页面，只有在人们真的会回来看它的时候，才算得上真正值得去搭建。这是一个比单纯拥有它要高得多的标准，而大多数页面恰恰就是在这个标准上跌了跤：页面确实存在，footer 里也确实有一个链接，更新起来一阵一阵的，除了出事故的时候几乎没有人会去看它。真正把这两者区分开来的那些决定，早在任何东西被写出来之前就已经做完了，而这些决定所关心的，主要是这个页面到底应该放在哪里，以及从同一份内容里还能生成出什么别的东西。
体验日志页面到底是什么
它是一份公开的、带有日期的列表，记录着一个产品到底发生了什么变化，放在一个属于你自己的 URL 上。它是可以承载同一批记录的五种表现形式之一，而真正有用的问题，从来都不是该选哪一种，而是哪一种才是最权威的那一份，哪些又只是从它那里生成出来的。
| 表现形式 | 最适合用于 | 成本 |
|---|---|---|
| 托管页面 | 搜索、链接、长期的历史记录 | 一个 URL 和一份模板 |
| 应用内小组件 | 触达那些永远不会主动访问页面的用户 | 一次嵌入，以及足够的克制 |
| 文档中的一个板块 | 面向 API 和开发者的读者群体 | 把它放在参考文档旁边 |
| JSON feed | 在你的变更之上继续构建的客户 | 你早已具备的结构化数据 |
| RSS feed | 只订阅一次的开发者 | 几乎没有任何成本 |
请选定一个权威的信息来源，只发布一次，剩下的全部从那里自动生成出来。那些用手工分别维护页面和小组件的团队，最终往往会得到两份对不上的文本，而这种不一致，最后总是由客户来替你发现。
体验日志页面到底应该放在哪里
放在你自己的域名下，放在一个稳定的路径上，让每一条记录都能通过一个片段或者一个独立的路径被单独定位。人们会在事故复盘和内部工单里引用这些记录，而一条无法被直接链接的记录，最终只会被当成一张截图贴出来。
三种常见的放置方式，分别是主站上的一个路径、一个子域名，以及文档里的一个板块。主站上的一个路径，是那个默认应该被反对的选项，而不是默认应该被支持的选项：它继承了整个站点的权威性，不需要额外的证书或 DNS，还能让这个页面和其他一切内容保持在同一套导航体系之下。
一个子域名之所以会成为正确的答案，是因为这个页面由一套和市场营销站点完全不同的系统来提供服务，否则你就只能去做反向代理了。它的代价，是权威性会被分开累积。把体验日志放进文档里之所以是正确的，是当读者群体是开发者的时候，原因在API 体验日志一文中已有说明：读者往往本来就已经在那里了。
比选择本身更重要的是，记录必须能够被单独链接。人们会在事故复盘和内部工单里引用记录，而一条只能被描述成”体验日志，往下滚动”的记录，最终只会被当成截图贴出来，而不是被真正链接过去。
体验日志页面到底需要什么
五件事，而大多数页面恰恰在前两件上就出了问题。按变更逐条记录，并带有日期，最新的排在最前面。每条记录都配一个分类或者标签，好让读者能按感兴趣的类型去扫读。每条记录都有一个永久链接。一个订阅的入口。超过大约五十条记录之后，还需要一个搜索或者过滤功能。
剩下的都是可选的。截图有帮助，但也需要维护成本。作者署名在某些产品上能建立信任，在另一些产品上却只是噪音。版本号对某个 API 的调用方很重要，对几乎其他所有人都不重要。Keep a Changelog 如果你没有理由自创一套标签，就是一个相当合理的默认选择，而它的核心原则，即便你抛弃了其余的一切，也依然值得保留：日志是写给人看的。
如果你的产品是持续发布的，请按日期分组，而不是按版本分组。一个正在扫读”这是在我们九号那次事故之前还是之后”的读者，找的其实是一个日期，而一个按版本号来组织的页面，只会逼着他去做算术。
应该做成一个页面，还是应该做成一个应用内小组件
两者都要，但都从同一个信息来源生成。页面是搜索、链接和长期历史记录所在的地方。小组件则是你触达那些永远不会主动访问页面的绝大多数用户的方式，它之所以有效，是因为它出现在了用户已经在使用的那个产品里面。
小组件真正的失败方式，是打扰。一个要求用户为每一条记录都付出注意力的小红点，一周之内就会被永久性地无视掉，而这样一来，你就失去了那条真正重要的记录本该拥有的渠道。请从读者上一次查看之后开始计算未读数量，在第一次访问时就默默地把计数器种下去，这样才不会有人一上来就被一整年的历史记录堆出来的小红点吓到，并且要让读者自己去打开它，而不是替他打开。
如何让体验日志页面变得机器可读
请把同一批记录也发布成一条信息流。一条遵循 JSON Feed 规范 的 JSON feed，对于任何用代码去消费它的场景来说，都是摩擦最小的那个选项，而一条 RSS feed，则是一个在阅读器里订阅的开发者会期待看到的东西。一旦记录变成了结构化的数据，而不是手写的 HTML，这两者的成本都会很低，而这正是应该把权威副本保持结构化的真正原因。
也请给页面本身加上标记。每一条记录都是一件带有日期和标题的作品，而 schema.org 提供了相应的词汇表。这样做的理由和永久链接是一样的：它能让这个页面被那些并非浏览器的东西所使用，其中也包括客户自己的发布流程。如果底层的这些记录一开始就从来不是结构化数据，上面这一切都无从谈起；体验日志文件格式讲的正是 Markdown、JSON 和 YAML 各自要付出什么代价，才能成为这条信息流和这份标记真正被生成出来所依据的那个真相来源。
体验日志页面对 SEO 到底有没有帮助
间接地有，而且见效很慢。单独的一条记录很少能够排到搜索结果前面，因为它并没有针对任何一个真实存在的搜索词。这个页面真正靠的是链接来赢得自己的地位：这些记录会被引用在客服的回复里、论坛帖子里、事故复盘报告里，而这些链接又会不断累积到一个属于你自己的 URL 上。一个持续两年、每周都在更新的页面，本身也是它所属产品的一个可信的、新鲜度信号。
真正不奏效的做法，是把这些记录当成内容营销来对待。一条为了凑字数而被硬塞成三段的记录，在它真正该做的那件事上反而会做得更差，那件事就是用一句话告诉读者，他正在用的某个东西是不是发生了变化。如果你希望体验日志能够真正支持搜索，请把精力放在永久链接、信息流，以及指向它的内部链接上，并且让每条记录都保持简短。我们自己的体验日志范例页面，收集的正是一批把这种平衡拿捏得很好的页面。
人们到底是怎样订阅的
给他们提供他们本来就已经在用的那些渠道：给开发者提供 RSS 或 JSON feed，给那些只想听到重要事情的人提供邮件，给那些两者都永远不会去做的人提供应用内小组件。请去问他们到底想听到什么，而不是自己去假设，因为一个想要破坏性变更、结果却收到一堆文字修正的读者，最终会把两个渠道都取消订阅。
最后一个应该被加上的渠道，是能真正闭合整个循环的那一个。当一条记录解决了某个具体的人所提出的具体请求时，请直接告诉他，而不是指望他自己会去读那个页面。在 changeloop 里，一条记录会同时发布到页面、信息流和小组件上，而如果某个人的小组件反馈变成了 GitHub issue，并被这个 pull request 关闭，他就会在那个 issue 上连同一条指向该记录的链接一起收到通知，还会在小组件里看到这条记录。这套机制和任何一次订阅本质上都是一样的；唯一的区别，是这个接收者其实早就已经问过了。这正是在从体验日志这一侧闭合反馈循环一文中展开的论点。
FAQ
体验日志页面应该放在子域名上，还是放在一个路径下? 默认应该放在主站的一个路径下，因为它能继承整个站点的权威性，也不需要额外的基础设施。只有当页面确实是由另一套不同的系统来提供服务时，子域名才是合理的选择。
页面一次应该展示多少条记录? 足够填满一屏就行，不要更多，之后再用分页来处理。把两年的历史记录一次性加载进同一份文档里，速度会很慢，也会让人更难找到最新的那一条。
旧的记录到底应不应该被删除? 不应该。它们会被你站点之外的地方引用，删掉之后链接就会失效。请就地对某条记录做修正，并附上一条说明，同时让那个 URL 继续保持可访问。
是不是每一次变更都必须出现在这个页面上? 只有用户可能会注意到的那些才需要。一个连内部重构都记录进去的页面，只会训练读者养成一目十行的习惯，而一个被一目十行读过去的页面，恰恰会在它真正承载了紧急信息的那一天彻底失效。
本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。