プロジェクトに適した指標を選択する

このガイドは、より良いドキュメント化によってどのような種類の問題が解決される可能性があるか、またドキュメント プロジェクトに適した指標を選択する方法を組織が理解できるようにすることを目的としています。

現在のフェーズ:
結果発表。タイムラインをご覧ください。

問題を説明する

指標の選択に入る前に、解決しようとしている問題を十分に理解していることを確認してください。できるだけ具体的にご記入ください。

  • 「オンボーディング ドキュメントの pull リクエストのマージに時間がかかりすぎています。 寄与者はあきらめて去ってしまいます。」
  • 「エラーコードを理解するために、多くの問題が未解決になっています。」
  • 「当社の CI/CD パイプラインは不安定です。理解が不十分な理由で不合格になるテストが多すぎる。」
  • 「週 1 回のミーティングでは、メンバーが不機嫌そうに感じています。」

仮説を立てる

原因と結果を探る。おっしゃった問題の原因として何が考えられますか？問題には複数の原因や重複する原因があることに注意してください。

  • 「スタイルに関する明確なガイダンスがないため、オンボーディング ドキュメントの pull リクエストのマージに時間がかかります。レビュー担当者は、やるべきことがわからないため PR のレビューを後回しにするか、形式について寄与者と何度も行き来します。」
  • 「ドキュメントにエラーコードに関する情報がないため、ユーザーは問題を報告する必要があります。」
  • 「プロバイダでプランの制限やタイムアウトが発生したため、CI/CD テストが失敗します。」
  • 「毎週のミーティングは、各自のタイムゾーンの午前 5 時 30 分に始まるため、参加者が不満を抱えています。」

ソリューションを提案する

この問題は、新しいドキュメントやより良いドキュメントで解決できる問題でしょうか？

  • 「スタイルガイドがあれば、コミッターが PR を送信する前にチェックできます。何を確認すればよいのか、レビュアーはわかっていました。レビュー担当者や寄稿者は、書式、トーン、スタイルについて議論する必要がなくなります。」
  • 「エラーコードのドキュメントがあれば、ユーザーは問題をオープンする代わりに、そこで答えを見つけることができました。」
  • 「うーん。より良いドキュメントで CI/CD の問題を解決できるとは思えません。」
  • 「ミーティングの始めにノックノック ジョークを出すこともできます。ノックノック ジョークのコレクションを作っていれば、笑顔で会議を始めることができます。」

具体的な

問題を数値化できるか

  • 「『PR の統合に時間がかかりすぎる』とはどういう意味ですか？2 か月？2 週間？コントリビューターは審査をどのくらい待ってからあきらめますか？」
  • 「『問題が多すぎる』とは何件のエラーコード関連の問題ですか？」
  • 「うーん...『不機嫌』なんて気まずいじゃない？」

測定可能性を確認する

提案された指標をどのように確認しますか？簡単かつ正確に測定できるか？測定は誰が行うかによって決まるか？

  • 「pull リクエストがオープンされている期間と、審査がリクエストされてからの期間を簡単に測定できます。貢献者がいつ諦めたかを正確に測定することはできません”
  • 「「error-code」とタグ付けされた問題を数えるか、問題内を検索してエラーコード テキストを検索できます。」
  • 「人の不機嫌さを巧妙に、あるいは正確に測定できない。」

サブの指標を追加

ドキュメントが問題を解決しているかどうかを把握するのに役立つ他の指標はありますか？ターゲット指標はすべてのケースで同じか？

  • 「PR が長いほど審査に時間がかかります。PR のサイズごとに異なるしきい値を使用する必要があります。小規模、中規模、大規模、そして巨大 PR のマージに要する時間を測定したいのです。」
  • 「エラーコードのドキュメントが受信したアクセス数をチェックして、その数字が未解決の問題の減少と相関しているかどうかを確認することができます。」

期間を選択する

  • 「中小規模の PR を統合するには 2 週間が妥当です。すべての PR は 1 か月以内に統合する必要があります。2 週間ごとに測定するわけです」
  • 「エラーコードに関連する問題の数を毎日更新することは意味がありません。問題をクローズするまでに通常 1 週間かかるからです。週に 1 回測定します。」

目標の設定

プロジェクトが成功したことを示すには、選択した指標にどの程度の変更が必要か。選択した指標について定量的な目標を設定することを検討してください。

  • 「すべての新規 PR を 1 か月以内に成約するという目標を達成できれば、成功となります。大規模な PR を成立させるまでの平均時間が 2 週間短縮されるとしたら、大きな成功となるでしょう。」
  • 「理想的には、新たなエラー関連の問題が発生しないはずです。しかし、エラー関連の問題が 50% 減少したら、プロジェクトは成功したと考えることができます。」