为项目选择合适的指标

本指南旨在帮助组织了解可以通过更好的文档解决哪些类型的问题，以及如何为文档项目选择合适的指标。

当前阶段：
公布结果。请参阅时间表。

说明你的问题

在开始选择指标之前，请确保您已充分了解自己尝试解决的问题。请尽量具体说明。

  • “针对我们新手入门文档的拉取请求合并起来耗时太长。贡献者会放弃，然后消失。”
  • “我们发现有太多问题未解决，无法帮助理解错误代码。”
  • “我们的 CI/CD 流水线不稳定。太多测试由于无法理解的原因而失败。”
  • “我们每周的会议都让人感到不满。”

提出一个假设

查明因果关系。导致您所说的问题的原因可能是什么？请注意，问题可能由多种原因或重叠的原因导致。

  • “合并入职文档的拉取请求需要很长时间，因为我们没有关于样式的明确指导。审核者要么因为不知道该怎么做而推迟审核 PR，要么与贡献者讨论格式设置反复进行沟通。”
  • “用户不得不提交问题，因为他们无法在文档中找到有关错误代码的信息。”
  • “我们的 CI/CD 测试失败，因为我们遇到了提供商的计划限制和超时问题。”
  • “我们每周的会议都让人不舒服，因为开会的时间是所在时区的凌晨 5:30。”

提出解决方案

这个问题能否通过新的或更好的文档来解决？

  • “如果有风格指南，提交者可以在提交 PR 之前进行查看。审核者会知道需要检查哪些内容。审核者和贡献者无需争论格式、语气和风格。”
  • “如果我们有错误代码文档，用户就可以在此处找到答案，而无需打开问题。”
  • “嗯，更好的文档似乎并不能解决我们的 CI/CD 问题。”
  • “每次会议开始时，我们都可以讲一个敲门砖的笑话！制作一系列敲门声的笑话有助于我们在开会时愉快地开会。”

获取具体信息

您能量化这个问题吗？

  • “‘合并 PR 需要花太多时间’”到底是什么意思？两个月？两周？贡献者将在多长时间内等待审核才能放弃？”
  • “有多少与错误代码相关的问题‘问题过多’？”
  • “嗯...‘过于暴脾气’有多暴躁？”

检查可衡量性

您如何查看提议的指标？是否能轻松准确地进行衡量？衡量是否取决于测量人员？

  • “我们可以轻松衡量拉取请求处于待处理状态的时间，以及自请求审核以来已过去多长时间。我们无法准确衡量贡献者何时放弃。”
  • “我们可以统计有多少问题标记为‘错误代码’，或在问题中搜索错误代码文本。”
  • “我们无法以巧妙或准确的方式衡量人们的暴躁情绪。”

添加次要指标

是否有其他指标可以帮助您了解文档是否解决了您的问题？在所有情况下，您的目标指标是否相同？

  • “更长的 PR 需要更多的审核时间；我们应该针对不同大小的 PR 设定不同的阈值。我们希望衡量小型、中型、大型和巨型 PR 的合并时间。”
  • “我们可以查看错误代码文档收到多少次访问，看看这个数字是否意味着打开的问题更少。”

选择一个时间段

  • “我们认为，合并中小型 PR 需要两周时间进行合并；所有 PR 应在一个月内合并。所以我们每两周会衡量一次。”
  • “每天更新与错误代码相关的问题的数量没有意义，因为我们通常在一周时间关闭一个问题。我们将每周进行一次衡量。”

设定目标

您需要在所选指标中看到多大的变化才能确定该项目取得了成功？考虑为您所选的指标设置量化目标。

  • “如果我们在一个月内完成每个新公关的目标，那就非常成功。如果完成大型 PR 的平均时间缩短了两周，那将是一个巨大的成功。”
  • “理想情况下，我们不会看到与错误相关的新问题。但如果我们发现提出的错误相关问题数量减少 50%，我们便会认为我们的项目成功了。”