为项目选择合适的指标

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

当前阶段：
2021 年“文档季”活动已于 2021 年 12 月 14 日结束。请参阅时间轴。

说明您的问题

在着手选择指标之前，请确保您充分了解自己要解决的问题。请尽量具体说明。

  • “我们的新手入门文档的拉取请求合并时间太长。 贡献者会放弃并离开。”
  • “我们发现，有太多用户提出了关于如何理解错误代码的帮助请求。”
  • “我们的 CI/CD 流水线不稳定。太多测试会因为难以理解的原因而失败。”
  • “我们的每周会议上，大家似乎都很不高兴。”

提出假设

找出因果关系。导致您所述问题的原因可能是什么？请注意，问题可能有多个原因或重叠的原因。

  • “合并新手入门文档的拉取请求需要很长时间，因为我们没有关于样式的明确指南。审核人员要么因为不知道该怎么做而推迟审核 PR，要么就格式问题与贡献者反复沟通。”
  • “用户必须提出问题，因为他们在文档中找不到有关错误代码的信息。”
  • “我们的 CI/CD 测试失败，因为我们遇到了提供商的方案限制和超时问题。”
  • “由于每周会议在他们的时区上午 5:30 举行，因此大家在会议中都很不耐烦。”

提出解决方案

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

  • “如果我们有风格指南，提交者可以在提交他们的 PR 之前对其进行检查。审核人员会知道要检查什么。审核者和贡献者不必再为格式、基调和风格争论。”
  • “如果我们有错误代码文档，用户就可以在其中找到答案，而无需打开问题。”
  • “嗯，更好的文档似乎无法解决我们的 CI/CD 问题。”
  • “我们可以开场说个敲门笑话！创建一系列敲门声的笑话有助于我们在开会时笑容满面。”

获取具体信息

您能否量化问题？

  • “‘合并 PR 需要太长时间’究竟是什么意思？两个月？两周？贡献者会等待多长时间的审核结果，然后才会放弃？”
  • “与错误代码相关的问题有多少属于‘问题过多’？”
  • “嗯…‘太暴躁’是什么程度？”

检查可衡量性

您如何检查您提议的指标？是否可以轻松准确地进行衡量？衡量结果是否取决于进行衡量的人？

  • “我们可以轻松衡量拉取请求的开放时间，以及请求审核后的等待时间。我们无法准确衡量贡献者何时放弃。”
  • “我们可以统计标记为‘error-code’的问题数量，或在问题中搜索错误代码文本。”
  • “我们无法以得体或准确的方式衡量人们的暴躁程度。”

添加次级指标

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

  • “PR 越长，审核时间就越长；我们应该针对不同大小的 PR 设置不同的阈值。我们希望衡量小型、中型、大型和超大型 PR 的合并时间。”
  • “我们可以查看错误代码文档收到的访问次数，看看该数字是否与问题数量减少相关。”

选择一个时间段

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

设定目标

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

  • “如果我们实现了在不到一个月的时间内完成所有新公关活动的目标，那就是成功了。如果我们缩短大型 PR 的平均完成时间两周，那将是巨大的成功。”
  • “理想情况下，应该不会再出现与错误相关的新问题。但如果我们发现与错误相关的问题减少了 50%，就会认为我们的项目取得了成功。”