本指南旨在協助機構瞭解改善說明文件可解決哪些問題，以及如何為說明文件專案選擇合適的指標。
目前階段：
結果已公布。請參閱時間表。
說明問題
在選擇指標之前，請先確保您充分瞭解要解決的問題。越明確越好。
- 「新手上路說明文件的 Pull Request 合併時間過長。協作者放棄並離開。」
- 「我們發現有太多問題需要協助瞭解錯誤代碼。」
- 「我們的 CI/CD 管道不穩定。許多測試失敗的原因不明。」
- 「每週開會時，大家似乎都很不耐煩。」
提出假設
找出原因和影響。請問問題可能出在哪裡？請注意，問題可能有許多或重疊的原因。
- 「新手上路文件的合併提取要求需要花費很長的時間，因為我們沒有明確的樣式指南。審查人員不知道該怎麼做，就會延遲審查 PR，或是與貢獻者討論格式問題。”
- 「使用者無法在說明文件中找到錯誤代碼相關資訊，因此必須提出問題。」
- 「我們的 CI/CD 測試失敗，因為我們遇到了供應商的方案限制和逾時問題。」
- 「每週會議在他們的時區凌晨 5 點半舉行，讓他們感到不悅。」
提出解決方案
這個問題是否可以透過新的或更完善的說明文件解決？
- 「如果我們有風格指南，提交 PR 前，提交者就能先查看指南。審查人員就能知道要檢查哪些項目。審查員和作者不必爭論格式、語氣和風格。」
- 「如果我們有錯誤代碼說明文件，使用者就能在其中找到答案，而不用提出問題。」
- 「嗯，看來更完善的文檔無法解決我們的 CI/CD 問題。」
- 「我們可以透過 Knock-Knock 笑話開始每場會議！建立一組敲門笑話，讓我們在會議開始時笑笑。”
具體說明
能否量化問題？
- 「『合併 PR 的時間太長』實際上是什麼意思？兩個月？兩週嗎？貢獻者會等待多久才放棄等待審查？」
- 「有多少個錯誤代碼相關問題才算是『太多問題』？」
- 「嗯… 什麼是『太暴躁』？」
檢查可評估性
您會如何檢查所提議的指標？是否可以輕鬆且準確地評估？測量結果是否取決於測量者？
- 「我們可以輕鬆評估拉取要求已開放多久，以及要求審查後的時間長度。我們無法準確評估貢獻者放棄的時間點。」
- 「我們可以計算標記為『error-code』的問題數量，或是在問題中搜尋錯誤代碼文字。」
- 「我們無法以委婉或準確的方式評估使用者的不耐煩程度。」
新增次要指標
是否有其他指標可協助您瞭解說明文件是否解決了您的問題？您在每個情況下設定的目標指標是否相同？
- 「較長的 PR 需要更多時間進行審查；我們應該為不同大小的 PR 設定不同的門檻。我們想評估小型、中型、大型和超大型提交要求的合併時間。」
- 「我們可以查看錯誤代碼說明文件的瀏覽次數，並瞭解這個數字是否與提出的問題減少有關。」
選擇時間範圍
- 「我們認為，合併小型至中型 PR 的合理時間為兩週；所有 PR 都應在一個月內合併。因此，我們會每兩週進行一次評估。」
- 「我們通常需要一週的時間才能關閉問題，因此每天更新錯誤代碼相關問題的數量並不合理。我們會每週進行評估。」
設定目標
您需要在所選指標中看到多少變化，才能說這個專案成功？建議您為所選指標設定定量目標。
- 「如果我們達成目標，在一個月內關閉所有新的 PR，那麼這就是成功。如果我們處理大型提交要求的平均時間縮短兩週，就算是巨大的成功。」
- 「理想情況下，我們不會看到任何新的錯誤相關問題。但如果錯誤相關問題的開啟率下降 50%，我們就會認為專案成功。」
相關資訊
- 如需報表相關工作方面的協助，請參閱機構管理員指南。