为项目选择合适的指标

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

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

说明您的问题

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

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

提出假设

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

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

提出解决方案

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

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

获取具体信息

您能否量化问题？

  • “‘合并 PR 需要太长时间’到底是什么意思？两个月？两周？贡献者在放弃之前需要等待多长时间才能收到审核结果？”
  • “有多少与错误代码相关的问题‘问题过多’？”
  • “嗯…‘太暴躁’是什么程度？”

检查可衡量性

您会如何检查自己提议的指标？该指标能否轻松准确地衡量？衡量结果是否取决于执行衡量工作的人员？

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

添加次级指标

还有哪些指标有助于您了解文档是否在解决问题？您的目标指标在每种情况下是否相同？

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

选择一个时间段

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

设定目标

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

  • “如果我们在不到一个月的时间里就实现了关闭每个新公关的目标，那就太好了。如果我们缩短大型 PR 的平均完成时间两周，那将是巨大的成功。”
  • “理想情况下，我们不会看到任何新的错误相关问题。但如果我们发现与错误相关的问题减少了 50%，就会认为我们的项目取得了成功。”