为项目选择合适的指标

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

当前阶段：
公布结果的时间表。

说明您的问题

在开始选择指标之前，请确保您充分了解自己尝试解决的问题。请尽可能具体一些。

  • “针对我们新手入门文档的拉取请求合并需要太长时间。 贡献者会放弃，然后离开。”
  • “我们发现有太多问题，我们无法帮助理解错误代码。”
  • “我们的 CI/CD 流水线不稳定。太多测试因为无法理解的原因导致失败。”
  • “在我们每周的会议上，大家看起来很郁闷。”

提出一个假设

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

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

提出解决方案

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

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

获取具体信息

您能量化这个问题吗？

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

检查可衡量性

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

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

添加次要指标

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

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

选择一个时间段

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

设定目标

要想判定该项目取得了成功，您需要在所选指标中看到怎样的变化？考虑为您选择的指标设定量化目标。

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