为项目选择合适的指标

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

当前阶段：
案例研究已发布。请参阅时间轴。

说明您的问题

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

  • “我们的新手入门文档的拉取请求合并时间过长。贡献者会放弃并离开。”
  • “我们发现有太多问题需要帮助来了解错误代码。”
  • “我们的 CI/CD 流水线不稳定。太多测试因原因不明而失败。”
  • “我们的每周会议似乎让大家感到不快。”

提出假设

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

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

提出解决方案

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

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

具体说明

您能否量化问题？

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

检查可衡量性

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

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

添加次级指标

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

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

选择一个时间段

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

设定目标

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

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