このガイドは、より優れたドキュメントで解決できる問題の種類と、ドキュメント プロジェクトに適した指標を選択する方法を組織が理解できるようにすることを目的としています。
現在のフェーズ:
ドキュメントの作成。タイムラインをご覧ください。
問題を説明する
指標の選択を開始する前に、解決しようとしている問題を十分に理解していることを確認してください。できるだけ具体的にご記入ください。
- 「オンボーディング ドキュメントの pull リクエストは、統合に時間がかかりすぎます。寄与者はあきらめて去ってしまいます。」
- 「エラーコードの理解をサポートするため、あまりにも多くの問題が開かれています。」
- 「当社の CI/CD パイプラインは不安定です。理解が不十分な理由で不合格になるテストが多すぎます。」
- 「毎週のミーティングでは、みんなが不満を感じているようです。」
仮説を立てる
原因と結果を探る。おっしゃった問題の原因として何が考えられますか？問題には複数の原因や重複する原因があることに注意してください。
- 「スタイルに関する明確なガイダンスがないため、オンボーディング ドキュメントの 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% 減少した場合には、プロジェクトは成功したと見なします。」
関連情報
- レポート関連のタスクについては、組織管理者ガイドをご覧ください。