衡量文档记录的成功程度

“是的，但是如何衡量成功呢？”

这无疑是最常被提及的一句话，不仅在开发者关系或开发者体验领域，在我们如今身处的敏捷世界中也是如此。事实上，你可能非常忙碌，但却无法交付任何真正可衡量的业务价值。这通常是对你技能的浪费，也是对雇主的负担。最终，谁都不是赢家。

我们来思考一下开发者体验，就本文而言，它大致指的是所有能够帮助开发者的事物。如果文档存在、编写良好且被开发者使用，这难道还不足以称之为成功吗？或许它甚至不需要编写得多么出色，只要存在就行。如果开发者使用它，这难道不算成功吗？

当然，这取决于你的目标，也许这样就算成功了。只要有一个独立的、非员工的页面浏览量，就可能符合你的成功标准。有人看过了！有人启用了！我们成功了！在这种情况下，成功实际上只是证明它已经上线了。

这只是最基本、最肤浅意义上的赋能。你有了文档，公司外部的人也能看到。但我非常怀疑提问者会认为这是一个可以接受的答案。而且从长远来看，这对你来说也不应该是个可以接受的答案！

我的目标是什么？

正如我上面所暗示的，我编写文档的目标就是为了赋能。

第一步是要向几乎所有人（包括你自己）承认，这很难。你需要根据你的社群、公司目标，甚至可能包括你所在的行业来不断迭代改进。

你越了解你的社区，就越能确定哪些指标是可以衡量的。照搬照抄、千篇一律的指标不仅无益，反而会适得其反。

我需要测量什么？

我希望我的文档能够让我的开发者社区、现有企业客户和我的内部同事高效、愉快地获取他们需要的信息。

这意味着我将围绕以下主题和领域来制定我的成功指标：

外部的

• 虚荣指标（页面浏览量、跳出率、着陆页）
• 互动指标（星级评分、评论）
• 搜索结果为零，搜索词关键词（如果您想在以后的文章中看到我对此的看法，请留言）
• 每季度每次发布更新的内容百分比

内部的

• 与技术支持部门合作，减少“如何操作”这类一键式问题的数量。
• 与咨询、客户成功、现场运营等部门合作，将用户体验类型的反馈融入文档体验（提高文档的可查找性和可搜索性）。
• 与产品管理团队合作，制定产品/项目的成功指标
• 执行文档相关项目（文档维护、平台重构等）的能力

缺乏背景信息的数据是危险的！

所有这些都带有很大的附加条件。仅仅提供这些数据而缺乏上下文信息，可能会导致一些错误。

虚荣指标

虚荣指标是很好的直觉检验。你的文档是否上线？表现最佳的页面是否保持了其领先地位？

根据文档类型的不同，这些虚荣指标可能与营销页面略有不同。例如，术语表的页面停留时间可能较短，跳出率较高。概念性文章的页面停留时间可能较长，表现与着陆页内容类似。两者都符合预期。

在之前的公司，我们表现最差的页面一直是卸载指南。现在也一样。卸载体验非常直观（而且完全没必要），所以这篇文章只是为了尽职调查而写的，它无需安装软件就能解答“我可以轻松卸载这个软件吗？”这个问题。

还有一些其他方面需要注意——退出页面是什么？入口页面是什么？这些是否符合您的预期？对这些列表的调整可以很好地表明文档编制工作是否成功。

参与度指标

沉默的开发者要么是快乐的开发者，要么是困惑到无法清晰表达自己需要什么才能摆脱困惑的人。这就再次说明了了解你的社区的重要性。

有些开发者和开发者角色以默默地钻研文档而闻名，而另一些开发者则会在社交媒体上大肆抱怨。

您的开发人员可能是一个爱说话的群体，他们愿意在您的文档、论坛或现场运营互动中留下评论、问题和疑虑。

遗憾的是，文档上的评论区很容易变成噪音。在我看来，任何评论都代表着参与，即使是“这部分有问题”这样的评论。他们找到了文档，找到了参与的方式，至少也提供了一个机会，让其他人有机会重新审视文档内容，使其更加清晰易懂。

当然，更多信息性的评论必然会给我们提供更多线索，但这将在另一篇博客中讨论。

内部合作伙伴

你会注意到，在分析内部合作伙伴时，我没有非常清楚地说明具体的衡量标准。这是有意为之。

您可以分享一些成功指标，例如，降低“如何操作”这类一键式支持请求的工单数量。这些指标虽然会产生一些干扰，但也能凸显出一些清晰的改进机会。通过与技术支持团队合作，您可以查看这些模式（最好能以报告的形式呈现），创建或修改现有文档，并监控与该主题相关的一键式工单数量，理论上这些工单数量应该会下降。

现在，合作至关重要，因为根据支持服务的衡量标准，您为开发人员提供更好、更清晰的文档（从而减少一次性工单）所做的工作，不仅会影响他们收到的工单数量，还会影响他们解决这些工单的速度。一次性工单虽然可以快速解决，但业务价值较低。减少一次性工单可以释放技术支持人员的资源，让他们能够处理更多需要更多人参与、更复杂、业务价值更高的工单。

同样，与面向外部的其他团队合作，找出潜在文档中的不足之处至关重要，这有助于确定是否存在可以重复使用的现有资产或材料，或者这些信息是否是故意不公开的。或许这些信息受企业许可或特定合同的限制。千万别泄露你的独家秘方！

总而言之，为了项目的成功而无意中得罪了内部合作伙伴，是不会赢得朋友的。

成功源于健康的团队

在其他团队或项目中行之有效的指标往往被忽略了一点：就像工程领域一样，文档也存在技术债务。对文档库进行维护，例如审查、更新、归档和其他优化活动，对于文档的健康至关重要。无论文档​​是由产品工程师维护，还是由专门的技术文档撰写团队维护，都需要预留一些时间来消除这些文档技术债务。

成功的文档编写并不意味着每次发布都要更新整个语料库。对于老旧、规模较大的软件平台来说，这种方法根本无法扩展。衡量初始基线并以此为目标，是检验团队是否不仅能够编写功能文档，还能兼顾维护工作的有效方法之一。

我认为这个问题包含外部和内部两个方面。外部方面，你可以通过 PR、发布说明或文档上“已更新”徽章的数量来查看新版本或发布更新了多少页面。内部方面，如果你维护着一个待办事项列表，那么其中有多少基于文档的待办事项得到了处理？或者有多少原本计划处理但因为要先维护新功能文档而被忽略了？

一个功能没有文档或文档不完善，就如同缺少一个功能一样，有些文档维护者对此深有体会。平衡新功能的文档编写和现有文档的维护，对于整个文档库和团队的健康至关重要。如果维护人员疲惫不堪，你的文档工作就无法成功。

总结一下

这其中还有很多值得探讨的地方，但这确实是一个很好的出发点。我最担心的是过分依赖虚荣指标。页面浏览量固然不错，但它更多地反映了你的SEO现状。页面浏览量对提升品牌知名度很有帮助，但可能对用户赋能的作用不大，最终取决于你的社群、公司以及你的目标。

我很想知道大家是否也有同感。鉴于 Camunda 的文档编写是产品工程（撰稿人）和开发者体验（策略）团队共同努力的成果，成功指标与赋能目标紧密相关。

如何衡量文档工作的成功？

非常感谢Ali的这条推文，它启发了我写下这些回复。强烈推荐大家也去看看那里的回复。

封面照片由Patricia Serna拍摄，来自Unsplash。